From 7533072a68ce4060bb530cc95055019c00afc527 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Fri, 11 Feb 2022 13:44:31 -0800 Subject: [PATCH 01/11] one part of the config doc --- .../configuration/config_documentation.md | 2827 +++++++++++++++++ 1 file changed, 2827 insertions(+) create mode 100644 docs/usage/configuration/config_documentation.md diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md new file mode 100644 index 000000000000..d11c3a0fb24d --- /dev/null +++ b/docs/usage/configuration/config_documentation.md @@ -0,0 +1,2827 @@ +## Welcome + +This is intended as a guide to the synapse configuration-each config option is documented, including instructions +on how to change the default and what sort of behavior to expect if the default is changed, and an example +configuration. If you don't want to spend a lot of time thinking about options, the config as generated sets sensible defaults +for most values. [which values must you fill in? server name, ports?, public base url?] + +## 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. + +## List of config options in the order in which they are found in the real config + +Config option: `modules` + +Server admins can expand Synapse's functionality with external modules. +See https://matrix-org.github.io/synapse/latest/modules/index.html for more +documentation on how to configure or create custom modules for Synapse. + +Example configuration: +``` +modules: + - module: my_super_module.MySuperClass + config: + do_thing: true + - module: my_other_super_module.SomeClass + config: {} +``` +--- +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 https://matrix-org.github.io/synapse/latest/delegate.html +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. + +Example configuration #1: +``` +server_name: matrix.org +``` +Example configuration #2: +``` +server_name: localhost:8080 +``` +--- +Config option: `pid_file` + +When running Synapse as a daemon, the file to store the pid in. + +Example configuration: +``` +pid_file: DATADIR/homeserver.pid +``` +--- +Config option: `web_client_location` + +The absolute URL to the web client which `/` will redirect to. + +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:///`. + +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:///` on port 443 is routed to Synapse, this +option configures Synapse to serve a file at `https:///.well-known/matrix/server`. +This will tell other servers to send traffic to port 443 instead. + +Uncomment this option in the config to tell other servers to send federation traffic on +port 443, as 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. + +Example configuration: +``` +soft_file_limit: 0 +``` +--- +Config option: `presence` + +Presence tracking allows users to see the state (e.g online/offline) +of other local and remote users. Uncomment the `enabled` flag below `presence` to +disable presence tracking on this homeserver. 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` + +Uncomment 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` + +Uncomment 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. + +Known room versions are listed here: +https://spec.matrix.org/latest/rooms/#complete-list-of-room-versions + +For example, for room version 1, `default_room_version` should be set +to "1". + +Example configuration: +``` +default_room_version: "6" +``` +--- +Config option: `gc_thresholds` + +The garbage collection threshold parameters to pass to `gc.set_threshold`, if defined. + +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. -1 means no upper limit. + +Uncomment to increase the limit to 5000 or set your own value. + +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 disabled, new messages will not be indexed for searching and users +will receive errors when searching for messages. Defaults to enabled. + +Example configuration: +``` +enable_search: false +``` +--- +Config option: `ip_range_blacklist` + +This option prevents outgoing requests from being sent to the following 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. + +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 https://matrix-org.github.io/synapse/latest/manhole.html), + +        `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), + +        `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). + +        `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. 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 https://matrix-org.github.io/synapse/latest/consent_tracking.html. + +`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 https://matrix-org.github.io/synapse/latest/metrics-howto.html. + +    `openid`: OpenID authentication. + +`replication`: the HTTP replication API (/_synapse/replication). See https://matrix-org.github.io/synapse/latest/workers.html. + +`static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) + +Example configuration #1: +``` +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: +``` + # 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 optoin: `manhole_settings` + +Connection settings for the manhole. Link to manhole docs. + +Example configuration: +``` +manhole_settings: + # The username for the manhole. This defaults to 'matrix'. + username: manhole + + # The password for the manhole. This defaults to 'rabbithole'. + password: mypassword + + # 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. + 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 +``` +--- +Config option: `admin_contact` + +How to reach the server admin, used in `ResourceLimitError`. + +Example configuration: +``` +admin_contact: 'mailto:admin@server.com' +``` +--- +Config option: `hs_disabled` + +Config option: `hs_disabled_message` + +Example configuration: +``` +hs_disabled: false +hs_disabled_message: 'Human readable 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`. + +Example configuration: +``` +limit_usage_by_mau: false +``` +--- +Config option: `max_mau_value` + +This option sets the hard limit of monthly active users above which the server will start blocking user actions. + +Example configuration: +``` +max_mau_value: 50 +``` +--- +Config option: `mau_trial_days` + +# 'mau_trial_days' is a means to add a grace period for active users. It +# means that users must be active for this 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. +# +# '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 +# +#limit_usage_by_mau: false +#max_mau_value: 50 +#mau_trial_days: 2 +#mau_limit_alerting: false + +# If enabled, the metrics for the number of monthly active users will +# be populated, however no one will be limited. If limit_usage_by_mau +# is true, this is implied to be true. +# +#mau_stats_only: false + +# Sometimes the server admin will want to ensure certain accounts are +# never blocked by mau checking. These accounts are specified here. +# +#mau_limit_reserved_threepids: +# - medium: 'email' +# address: 'reserved_user@example.com' + +# Used by phonehome stats to group together related servers. +#server_context: context + +# Resource-constrained homeserver settings +# +# When this 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. +# +# Room complexity is an arbitrary measure based on factors such as the number of +# users in the room. +# +limit_remote_rooms: + # Uncomment to enable room complexity checking. + # + #enabled: true + + # the limit above which rooms cannot be joined. The default is 1.0. + # + #complexity: 0.5 + + # override the error which is returned when the room is too complex. + # + #complexity_error: "This room is too complex." + + # allow server admins to join complex rooms. Default is false. + # + #admins_can_join: true + +# Whether to require a user to be in the room to add an alias to it. +# Defaults to 'true'. +# +#require_membership_for_aliases: false + +# Whether to allow per-room membership profiles through the send of membership +# events with profile information that differ from the target's global profile. +# Defaults to 'true'. +# +#allow_per_room_profiles: false + +# The largest allowed file size for a user avatar. Defaults to no restriction. +# +# Note that user avatar changes will not work if this is set without +# using Synapse's media repository. +# +#max_avatar_size: 10M + +# The MIME types allowed for user avatars. Defaults to no restriction. +# +# Note that user avatar changes will not work if this is set without +# using Synapse's media repository. +# +#allowed_avatar_mimetypes: ["image/png", "image/jpeg", "image/gif"] + +# How long to keep redacted events in unredacted form in the database. After +# this period redacted events get replaced with their redacted form in the DB. +# +# Defaults to `7d`. Set to `null` to disable. +# +#redaction_retention_period: 28d + +# How long to track users' last seen time and IPs in the database. +# +# Defaults to `28d`. Set to `null` to disable clearing out of old rows. +# +#user_ips_max_age: 14d + +# Inhibits the /requestToken endpoints from returning an error that might leak +# information about whether an e-mail address is in use or not on this +# homeserver. +# Note that for some endpoints the error situation is the e-mail already being +# used, and for others the error is entering the e-mail being unused. +# If this option is enabled, instead of returning an error, these endpoints will +# act as if no error happened and return a fake session ID ('sid') to clients. +# +#request_token_inhibit_3pid_errors: true + +# A list of domains that the domain portion of 'next_link' parameters +# must match. +# +# This parameter is optionally provided by clients while requesting +# validation of an email or phone number, and maps to a link that +# users will be automatically redirected to after validation +# succeeds. Clients can make use this parameter to aid the validation +# process. +# +# The whitelist is applied whether the homeserver or an +# identity server is handling validation. +# +# The default value is no whitelist functionality; all domains are +# allowed. Setting this value to an empty list will instead disallow +# all domains. +# +#next_link_domain_whitelist: ["matrix.org"] + +# Templates to use when generating email or HTML page contents. +# +templates: + # Directory in which Synapse will try to find template files to use to generate + # email or HTML page contents. + # If not set, or a file is not found within the template directory, a default + # template from within the Synapse package will be used. + # + # See https://matrix-org.github.io/synapse/latest/templates.html for more + # information about using custom templates. + # + #custom_template_directory: /path/to/custom/templates/ + + +# Message retention policy at the server level. +# +# Room admins and mods can define a retention period for their rooms using the +# 'm.room.retention' state event, and server admins can cap this period by setting +# the 'allowed_lifetime_min' and 'allowed_lifetime_max' config options. +# +# If this feature is enabled, Synapse will regularly look for and purge events +# which are older than the room's maximum retention period. Synapse will also +# filter events received over federation so that events that should have been +# purged are ignored and not stored again. +# +retention: + # The message retention policies feature is disabled by default. Uncomment the + # following line to enable it. + # + #enabled: true + + # Default retention policy. If set, Synapse will apply it to rooms that lack the + # 'm.room.retention' state event. Currently, the value of 'min_lifetime' doesn't + # matter much because Synapse doesn't take it into account yet. + # + #default_policy: + # min_lifetime: 1d + # max_lifetime: 1y + + # Retention policy limits. If set, and the state of a room contains a + # 'm.room.retention' event in its state which contains a 'min_lifetime' or a + # 'max_lifetime' that's out of these bounds, Synapse will cap the room's policy + # to these limits when running purge jobs. + # + #allowed_lifetime_min: 1d + #allowed_lifetime_max: 1y + + # Server admins can define the settings of the background jobs purging the + # events which lifetime has expired under the 'purge_jobs' section. + # + # If no configuration is provided, a single job will be set up to delete expired + # events in every room daily. + # + # Each job's configuration defines which range of message lifetimes the job + # takes care of. For example, if 'shortest_max_lifetime' is '2d' and + # 'longest_max_lifetime' is '3d', the job will handle purging expired events in + # rooms whose state defines a 'max_lifetime' that's both higher than 2 days, and + # lower than or equal to 3 days. Both the minimum and the maximum value of a + # range are optional, e.g. a job with no 'shortest_max_lifetime' and a + # 'longest_max_lifetime' of '3d' will handle every room with a retention policy + # which 'max_lifetime' is lower than or equal to three days. + # + # The rationale for this per-job configuration is that some rooms might have a + # retention policy with a low 'max_lifetime', where history needs to be purged + # of outdated messages on a more frequent basis than for the rest of the rooms + # (e.g. every 12h), but not want that purge to be performed by a job that's + # iterating over every room it knows, which could be heavy on the server. + # + # If any purge job is configured, it is strongly recommended to have at least + # a single job with neither 'shortest_max_lifetime' nor 'longest_max_lifetime' + # set, or one job without 'shortest_max_lifetime' and one job without + # 'longest_max_lifetime' set. Otherwise some rooms might be ignored, even if + # 'allowed_lifetime_min' and 'allowed_lifetime_max' are set, because capping a + # room's policy to these values is done after the policies are retrieved from + # Synapse's database (which is done using the range specified in a purge job's + # configuration). + # + #purge_jobs: + # - longest_max_lifetime: 3d + # interval: 12h + # - shortest_max_lifetime: 3d + # interval: 1d + + +## TLS ## + +# PEM-encoded X509 certificate for TLS. +# This certificate, as of Synapse 1.0, will need to be a valid and verifiable +# certificate, signed by a recognised Certificate Authority. +# +# Be sure to use a `.pem` file that includes the full certificate chain including +# any intermediate certificates (for instance, if using certbot, use +# `fullchain.pem` as your certificate, not `cert.pem`). +# +#tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" + +# PEM-encoded private key for TLS +# +#tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" + +# Whether to verify TLS server certificates for outbound federation requests. +# +# Defaults to `true`. To disable certificate verification, uncomment the +# following line. +# +#federation_verify_certificates: false + +# The minimum TLS version that will be used for outbound federation requests. +# +# Defaults to `1`. Configurable to `1`, `1.1`, `1.2`, or `1.3`. Note +# that setting this value higher than `1.2` will prevent federation to most +# of the public Matrix network: only configure it to `1.3` if you have an +# entirely private federation setup and you can ensure TLS 1.3 support. +# +#federation_client_minimum_tls_version: 1.2 + +# Skip federation certificate verification on the following whitelist +# of domains. +# +# This setting should only be used in very specific cases, such as +# federation over Tor hidden services and similar. For private networks +# of homeservers, you likely want to use a private CA instead. +# +# Only effective if federation_verify_certicates is `true`. +# +#federation_certificate_verification_whitelist: +# - lon.example.com +# - "*.domain.com" +# - "*.onion" + +# List of custom certificate authorities for federation traffic. +# +# This setting should only normally be used within a private network of +# homeservers. +# +# Note that this list will replace those that are provided by your +# operating environment. Certificates must be in PEM format. +# +#federation_custom_ca_list: +# - myCA1.pem +# - myCA2.pem +# - myCA3.pem + + +## Federation ## + +# Restrict federation to the following whitelist of domains. +# N.B. we recommend also firewalling your federation listener to limit +# inbound federation traffic as early as possible, rather than relying +# purely on this application-layer restriction. If not specified, the +# default is to whitelist everything. +# +#federation_domain_whitelist: +# - lon.example.com +# - nyc.example.com +# - syd.example.com + +# Report prometheus metrics on the age of PDUs being sent to and received from +# the following domains. This can be used to give an idea of "delay" on inbound +# and outbound federation, though be aware that any delay can be due to problems +# at either end or with the intermediate network. +# +# By default, no domains are monitored in this way. +# +#federation_metrics_domains: +# - matrix.org +# - example.com + +# Uncomment to disable profile lookup over federation. By default, the +# Federation API allows other homeservers to obtain profile data of any user +# on this homeserver. Defaults to 'true'. +# +#allow_profile_lookup_over_federation: false + +# Uncomment to disable device display name lookup over federation. By default, the +# Federation API allows other homeservers to obtain device display names of any user +# on this homeserver. Defaults to 'true'. +# +#allow_device_name_lookup_over_federation: false + + +## Caching ## + +# Caching can be configured through the following options. +# +# A cache 'factor' is a multiplier that can be applied to each of +# Synapse's caches in order to increase or decrease the maximum +# number of entries that can be stored. + +# The number of events to cache in memory. Not affected by +# caches.global_factor. +# +#event_cache_size: 10K + +caches: + # Controls the global cache factor, which is the default cache factor + # for all caches if a specific factor for that cache is not otherwise + # set. + # + # This can also be set by the "SYNAPSE_CACHE_FACTOR" environment + # variable. Setting by environment variable takes priority over + # setting through the config file. + # + # Defaults to 0.5, which will half the size of all caches. + # + #global_factor: 1.0 + + # A dictionary of cache name to cache factor for that individual + # cache. Overrides the global cache factor for a given cache. + # + # These can also be set through environment variables comprised + # of "SYNAPSE_CACHE_FACTOR_" + the name of the cache in capital + # letters and underscores. Setting by environment variable + # takes priority over setting through the config file. + # Ex. SYNAPSE_CACHE_FACTOR_GET_USERS_WHO_SHARE_ROOM_WITH_USER=2.0 + # + # Some caches have '*' and other characters that are not + # alphanumeric or underscores. These caches can be named with or + # without the special characters stripped. For example, to specify + # the cache factor for `*stateGroupCache*` via an environment + # variable would be `SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0`. + # + per_cache_factors: + #get_users_who_share_room_with_user: 2.0 + + # Controls how long an entry can be in a cache without having been + # accessed before being evicted. Defaults to None, which means + # entries are never evicted based on time. + # + #expiry_time: 30m + + # Controls how long the results of a /sync request are cached for after + # a successful response is returned. A higher duration can help clients with + # intermittent connections, at the cost of higher memory usage. + # + # By default, this is zero, which means that sync responses are not cached + # at all. + # + #sync_response_cache_duration: 2m + + +## Database ## + +# The 'database' setting defines the database that synapse uses to store all of +# its data. +# +# 'name' gives the database engine to use: either 'sqlite3' (for SQLite) or +# 'psycopg2' (for PostgreSQL). +# +# 'txn_limit' gives the maximum number of transactions to run per connection +# before reconnecting. Defaults to 0, which means no limit. +# +# 'args' gives options which are passed through to the database engine, +# except for options starting 'cp_', which are used to configure the Twisted +# connection pool. For a reference to valid arguments, see: +# * for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect +# * for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS +# * for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ +# +# +# Example SQLite configuration: +# +#database: +# name: sqlite3 +# args: +# database: /path/to/homeserver.db +# +# +# Example Postgres configuration: +# +#database: +# name: psycopg2 +# txn_limit: 10000 +# args: +# user: synapse_user +# password: secretpassword +# database: synapse +# host: localhost +# port: 5432 +# cp_min: 5 +# cp_max: 10 +# +# For more information on using Synapse with Postgres, +# see https://matrix-org.github.io/synapse/latest/postgres.html. +# +database: + name: sqlite3 + args: + database: DATADIR/homeserver.db + + +## Logging ## + +# A yaml python logging config file as described by +# https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema +# +log_config: "CONFDIR/SERVERNAME.log.config" + + +## Ratelimiting ## + +# Ratelimiting settings for client actions (registration, login, messaging). +# +# Each ratelimiting configuration is made of two parameters: +# - per_second: number of requests a client can send per second. +# - burst_count: number of requests a client can send before being throttled. +# +# Synapse currently uses the following configurations: +# - one for messages that ratelimits sending based on the account the client +# is using +# - one for registration that ratelimits registration requests based on the +# client's IP address. +# - one for checking the validity of registration tokens that ratelimits +# requests based on the client's IP address. +# - one for login that ratelimits login requests based on the client's IP +# address. +# - one for login that ratelimits login requests based on the account the +# client is attempting to log into. +# - one for login that ratelimits login requests based on the account the +# client is attempting to log into, based on the amount of failed login +# attempts for this account. +# - one for ratelimiting redactions by room admins. If this is not explicitly +# set then it uses the same ratelimiting as per rc_message. This is useful +# to allow room admins to deal with abuse quickly. +# - two for ratelimiting number of rooms a user can join, "local" for when +# users are joining rooms the server is already in (this is cheap) vs +# "remote" for when users are trying to join rooms not on the server (which +# can be more expensive) +# - one for ratelimiting how often a user or IP can attempt to validate a 3PID. +# - two for ratelimiting how often invites can be sent in a room or to a +# specific user. +# - one for ratelimiting 3PID invites (i.e. invites sent to a third-party ID +# such as an email address or a phone number) based on the account that's +# sending the invite. +# +# The defaults are as shown below. +# +#rc_message: +# per_second: 0.2 +# burst_count: 10 +# +#rc_registration: +# per_second: 0.17 +# burst_count: 3 +# +#rc_registration_token_validity: +# per_second: 0.1 +# burst_count: 5 +# +#rc_login: +# address: +# per_second: 0.17 +# burst_count: 3 +# account: +# per_second: 0.17 +# burst_count: 3 +# failed_attempts: +# per_second: 0.17 +# burst_count: 3 +# +#rc_admin_redaction: +# per_second: 1 +# burst_count: 50 +# +#rc_joins: +# local: +# per_second: 0.1 +# burst_count: 10 +# remote: +# per_second: 0.01 +# burst_count: 10 +# +#rc_3pid_validation: +# per_second: 0.003 +# burst_count: 5 +# +#rc_invites: +# per_room: +# per_second: 0.3 +# burst_count: 10 +# per_user: +# per_second: 0.003 +# burst_count: 5 +# +#rc_third_party_invite: +# per_second: 0.2 +# burst_count: 10 + +# Ratelimiting settings for incoming federation +# +# The rc_federation configuration is made up of the following settings: +# - window_size: window size in milliseconds +# - sleep_limit: number of federation requests from a single server in +# a window before the server will delay processing the request. +# - sleep_delay: duration in milliseconds to delay processing events +# from remote servers by if they go over the sleep limit. +# - reject_limit: maximum number of concurrent federation requests +# allowed from a single server +# - concurrent: number of federation requests to concurrently process +# from a single server +# +# The defaults are as shown below. +# +#rc_federation: +# window_size: 1000 +# sleep_limit: 10 +# sleep_delay: 500 +# reject_limit: 50 +# concurrent: 3 + +# Target outgoing federation transaction frequency for sending read-receipts, +# per-room. +# +# If we end up trying to send out more read-receipts, they will get buffered up +# into fewer transactions. +# +#federation_rr_transactions_per_room_per_second: 50 + + + +## Media Store ## + +# Enable the media store service in the Synapse master. Uncomment the +# following if you are using a separate media store worker. +# +#enable_media_repo: false + +# Directory where uploaded images and attachments are stored. +# +media_store_path: "DATADIR/media_store" + +# Media storage providers allow media to be stored in different +# locations. +# +#media_storage_providers: +# - module: file_system +# # Whether to store newly uploaded local files +# store_local: false +# # Whether to store newly downloaded remote files +# store_remote: false +# # Whether to wait for successful storage for local uploads +# store_synchronous: false +# config: +# directory: /mnt/some/other/directory + +# The largest allowed upload size in bytes +# +# If you are using a reverse proxy you may also need to set this value in +# your reverse proxy's config. Notably Nginx has a small max body size by default. +# See https://matrix-org.github.io/synapse/latest/reverse_proxy.html. +# +#max_upload_size: 50M + +# Maximum number of pixels that will be thumbnailed +# +#max_image_pixels: 32M + +# Whether to generate new thumbnails on the fly to precisely match +# the resolution requested by the client. If true then whenever +# a new resolution is requested by the client the server will +# generate a new thumbnail. If false the server will pick a thumbnail +# from a precalculated list. +# +#dynamic_thumbnails: false + +# List of thumbnails to precalculate when an image is uploaded. +# +#thumbnail_sizes: +# - width: 32 +# height: 32 +# method: crop +# - width: 96 +# height: 96 +# method: crop +# - width: 320 +# height: 240 +# method: scale +# - width: 640 +# height: 480 +# method: scale +# - width: 800 +# height: 600 +# method: scale + +# Is the preview URL API enabled? +# +# 'false' by default: uncomment the following to enable it (and specify a +# url_preview_ip_range_blacklist blacklist). +# +#url_preview_enabled: true + +# List of IP address CIDR ranges that the URL preview spider is denied +# from accessing. There are no defaults: you must explicitly +# specify a list for URL previewing to work. You should specify any +# internal services in your network that you do not want synapse to try +# to connect to, otherwise anyone in any Matrix room could cause your +# synapse to issue arbitrary GET requests to your internal services, +# causing serious security issues. +# +# (0.0.0.0 and :: are always blacklisted, whether or not they are explicitly +# listed here, since they correspond to unroutable addresses.) +# +# This must be specified if url_preview_enabled is set. It is recommended that +# you uncomment the following list as a starting point. +# +# Note: The value is ignored when an HTTP proxy is in use +# +#url_preview_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' + +# List of IP address CIDR ranges that the URL preview spider is allowed +# to access even if they are specified in url_preview_ip_range_blacklist. +# This is useful for specifying exceptions to wide-ranging blacklisted +# target IP ranges - e.g. for enabling URL previews for a specific private +# website only visible in your network. +# +#url_preview_ip_range_whitelist: +# - '192.168.1.1' + +# Optional list of URL matches that the URL preview spider is +# denied from accessing. You should use url_preview_ip_range_blacklist +# in preference to this, otherwise someone could define a public DNS +# entry that points to a private IP address and circumvent the blacklist. +# This is more useful if you know there is an entire shape of URL that +# you know that will never want synapse to try to spider. +# +# Each list entry is a dictionary of url component attributes as returned +# by urlparse.urlsplit as applied to the absolute form of the URL. See +# https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit +# The values of the dictionary are treated as an filename match pattern +# applied to that component of URLs, unless they start with a ^ in which +# case they are treated as a regular expression match. If all the +# specified component matches for a given list item succeed, the URL is +# blacklisted. +# +#url_preview_url_blacklist: +# # blacklist any URL with a username in its URI +# - username: '*' +# +# # blacklist all *.google.com URLs +# - netloc: 'google.com' +# - netloc: '*.google.com' +# +# # blacklist all plain HTTP URLs +# - scheme: 'http' +# +# # blacklist http(s)://www.acme.com/foo +# - netloc: 'www.acme.com' +# path: '/foo' +# +# # blacklist any URL with a literal IPv4 address +# - netloc: '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' + +# The largest allowed URL preview spidering size in bytes +# +#max_spider_size: 10M + +# A list of values for the Accept-Language HTTP header used when +# downloading webpages during URL preview generation. This allows +# Synapse to specify the preferred languages that URL previews should +# be in when communicating with remote servers. +# +# Each value is a IETF language tag; a 2-3 letter identifier for a +# language, optionally followed by subtags separated by '-', specifying +# a country or region variant. +# +# Multiple values can be provided, and a weight can be added to each by +# using quality value syntax (;q=). '*' translates to any language. +# +# Defaults to "en". +# +# Example: +# +# url_preview_accept_language: +# - en-UK +# - en-US;q=0.9 +# - fr;q=0.8 +# - *;q=0.7 +# +url_preview_accept_language: +# - en + + +# oEmbed allows for easier embedding content from a website. It can be +# used for generating URLs previews of services which support it. +# +oembed: + # A default list of oEmbed providers is included with Synapse. + # + # Uncomment the following to disable using these default oEmbed URLs. + # Defaults to 'false'. + # + #disable_default_providers: true + + # Additional files with oEmbed configuration (each should be in the + # form of providers.json). + # + # By default, this list is empty (so only the default providers.json + # is used). + # + #additional_providers: + # - oembed/my_providers.json + + +## Captcha ## +# See docs/CAPTCHA_SETUP.md for full details of configuring this. + +# This homeserver's ReCAPTCHA public key. Must be specified if +# enable_registration_captcha is enabled. +# +#recaptcha_public_key: "YOUR_PUBLIC_KEY" + +# This homeserver's ReCAPTCHA private key. Must be specified if +# enable_registration_captcha is enabled. +# +#recaptcha_private_key: "YOUR_PRIVATE_KEY" + +# Uncomment to enable ReCaptcha checks when registering, preventing signup +# unless a captcha is answered. Requires a valid ReCaptcha +# public/private key. Defaults to 'false'. +# +#enable_registration_captcha: true + +# The API endpoint to use for verifying m.login.recaptcha responses. +# Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify". +# +#recaptcha_siteverify_api: "https://my.recaptcha.site" + + +## TURN ## + +# The public URIs of the TURN server to give to clients +# +#turn_uris: [] + +# The shared secret used to compute passwords for the TURN server +# +#turn_shared_secret: "YOUR_SHARED_SECRET" + +# The Username and password if the TURN server needs them and +# does not use a token +# +#turn_username: "TURNSERVER_USERNAME" +#turn_password: "TURNSERVER_PASSWORD" + +# How long generated TURN credentials last +# +#turn_user_lifetime: 1h + +# Whether guests should be allowed to use the TURN server. +# This defaults to True, otherwise VoIP will be unreliable for guests. +# However, it does introduce a slight security risk as it allows users to +# connect to arbitrary endpoints without having first signed up for a +# valid account (e.g. by passing a CAPTCHA). +# +#turn_allow_guests: true + + +## Registration ## +# +# Registration can be rate-limited using the parameters in the "Ratelimiting" +# section of this file. + +# Enable registration for new users. +# +#enable_registration: false + +# Time that a user's session remains valid for, after they log in. +# +# Note that this is not currently compatible with guest logins. +# +# Note also that this is calculated at login time: changes are not applied +# retrospectively to users who have already logged in. +# +# By default, this is infinite. +# +#session_lifetime: 24h + +# Time that an access token remains valid for, if the session is +# using refresh tokens. +# For more information about refresh tokens, please see the manual. +# Note that this only applies to clients which advertise support for +# refresh tokens. +# +# Note also that this is calculated at login time and refresh time: +# changes are not applied to existing sessions until they are refreshed. +# +# By default, this is 5 minutes. +# +#refreshable_access_token_lifetime: 5m + +# Time that a refresh token remains valid for (provided that it is not +# exchanged for another one first). +# This option can be used to automatically log-out inactive sessions. +# Please see the manual for more information. +# +# Note also that this is calculated at login time and refresh time: +# changes are not applied to existing sessions until they are refreshed. +# +# By default, this is infinite. +# +#refresh_token_lifetime: 24h + +# Time that an access token remains valid for, if the session is NOT +# using refresh tokens. +# Please note that not all clients support refresh tokens, so setting +# this to a short value may be inconvenient for some users who will +# then be logged out frequently. +# +# Note also that this is calculated at login time: changes are not applied +# retrospectively to existing sessions for users that have already logged in. +# +# By default, this is infinite. +# +#nonrefreshable_access_token_lifetime: 24h + +# The user must provide all of the below types of 3PID when registering. +# +#registrations_require_3pid: +# - email +# - msisdn + +# Explicitly disable asking for MSISDNs from the registration +# flow (overrides registrations_require_3pid if MSISDNs are set as required) +# +#disable_msisdn_registration: true + +# Mandate that users are only allowed to associate certain formats of +# 3PIDs with accounts on this server. +# +#allowed_local_3pids: +# - medium: email +# pattern: '^[^@]+@matrix\.org$' +# - medium: email +# pattern: '^[^@]+@vector\.im$' +# - medium: msisdn +# pattern: '\+44' + +# Enable 3PIDs lookup requests to identity servers from this server. +# +#enable_3pid_lookup: true + +# Require users to submit a token during registration. +# Tokens can be managed using the admin API: +# https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html +# Note that `enable_registration` must be set to `true`. +# Disabling this option will not delete any tokens previously generated. +# Defaults to false. Uncomment the following to require tokens: +# +#registration_requires_token: true + +# If set, allows registration of standard or admin accounts by anyone who +# has the shared secret, even if registration is otherwise disabled. +# +#registration_shared_secret: + +# Set the number of bcrypt rounds used to generate password hash. +# Larger numbers increase the work factor needed to generate the hash. +# The default number is 12 (which equates to 2^12 rounds). +# N.B. that increasing this will exponentially increase the time required +# to register or login - e.g. 24 => 2^24 rounds which will take >20 mins. +# +#bcrypt_rounds: 12 + +# Allows users to register as guests without a password/email/etc, and +# participate in rooms hosted on this server which have been made +# accessible to anonymous users. +# +#allow_guest_access: false + +# The identity server which we suggest that clients should use when users log +# in on this server. +# +# (By default, no suggestion is made, so it is left up to the client. +# This setting is ignored unless public_baseurl is also explicitly set.) +# +#default_identity_server: https://matrix.org + +# Handle threepid (email/phone etc) registration and password resets through a set of +# *trusted* identity servers. Note that this allows the configured identity server to +# reset passwords for accounts! +# +# Be aware that if `email` is not set, and SMTP options have not been +# configured in the email config block, registration and user password resets via +# email will be globally disabled. +# +# Additionally, if `msisdn` is not set, registration and password resets via msisdn +# will be disabled regardless, and users will not be able to associate an msisdn +# identifier to their account. This is due to Synapse currently not supporting +# any method of sending SMS messages on its own. +# +# To enable using an identity server for operations regarding a particular third-party +# identifier type, set the value to the URL of that identity server as shown in the +# examples below. +# +# Servers handling the these requests must answer the `/requestToken` endpoints defined +# by the Matrix Identity Service API specification: +# https://matrix.org/docs/spec/identity_service/latest +# +account_threepid_delegates: + #email: https://example.com # Delegate email sending to example.com + #msisdn: http://localhost:8090 # Delegate SMS sending to this local process + +# Whether users are allowed to change their displayname after it has +# been initially set. Useful when provisioning users based on the +# contents of a third-party directory. +# +# Does not apply to server administrators. Defaults to 'true' +# +#enable_set_displayname: false + +# Whether users are allowed to change their avatar after it has been +# initially set. Useful when provisioning users based on the contents +# of a third-party directory. +# +# Does not apply to server administrators. Defaults to 'true' +# +#enable_set_avatar_url: false + +# Whether users can change the 3PIDs associated with their accounts +# (email address and msisdn). +# +# Defaults to 'true' +# +#enable_3pid_changes: false + +# Users who register on this homeserver will automatically be joined +# to these rooms. +# +# By default, any room aliases included in this list will be created +# as a publicly joinable room when the first user registers for the +# homeserver. This behaviour can be customised with the settings below. +# If the room already exists, make certain it is a publicly joinable +# room. The join rule of the room must be set to 'public'. +# +#auto_join_rooms: +# - "#example:example.com" + +# Where auto_join_rooms are specified, setting this flag ensures that the +# the rooms exist by creating them when the first user on the +# homeserver registers. +# +# By default the auto-created rooms are publicly joinable from any federated +# server. Use the autocreate_auto_join_rooms_federated and +# autocreate_auto_join_room_preset settings below to customise this behaviour. +# +# Setting to false means that if the rooms are not manually created, +# users cannot be auto-joined since they do not exist. +# +# Defaults to true. Uncomment the following line to disable automatically +# creating auto-join rooms. +# +#autocreate_auto_join_rooms: false + +# Whether the auto_join_rooms that are auto-created are available via +# federation. Only has an effect if autocreate_auto_join_rooms is true. +# +# Note that whether a room is federated cannot be modified after +# creation. +# +# Defaults to true: the room will be joinable from other servers. +# Uncomment the following to prevent users from other homeservers from +# joining these rooms. +# +#autocreate_auto_join_rooms_federated: false + +# The room preset to use when auto-creating one of auto_join_rooms. Only has an +# effect if autocreate_auto_join_rooms is true. +# +# This can be one of "public_chat", "private_chat", or "trusted_private_chat". +# If a value of "private_chat" or "trusted_private_chat" is used then +# auto_join_mxid_localpart must also be configured. +# +# Defaults to "public_chat", meaning that the room is joinable by anyone, including +# federated servers if autocreate_auto_join_rooms_federated is true (the default). +# Uncomment the following to require an invitation to join these rooms. +# +#autocreate_auto_join_room_preset: private_chat + +# The local part of the user id which is used to create auto_join_rooms if +# autocreate_auto_join_rooms is true. If this is not provided then the +# initial user account that registers will be used to create the rooms. +# +# The user id is also used to invite new users to any auto-join rooms which +# are set to invite-only. +# +# It *must* be configured if autocreate_auto_join_room_preset is set to +# "private_chat" or "trusted_private_chat". +# +# Note that this must be specified in order for new users to be correctly +# invited to any auto-join rooms which have been set to invite-only (either +# at the time of creation or subsequently). +# +# Note that, if the room already exists, this user must be joined and +# have the appropriate permissions to invite new members. +# +#auto_join_mxid_localpart: system + +# When auto_join_rooms is specified, setting this flag to false prevents +# guest accounts from being automatically joined to the rooms. +# +# Defaults to true. +# +#auto_join_rooms_for_guests: false + +# Whether to inhibit errors raised when registering a new account if the user ID +# already exists. If turned on, that requests to /register/available will always +# show a user ID as available, and Synapse won't raise an error when starting +# a registration with a user ID that already exists. However, Synapse will still +# raise an error if the registration completes and the username conflicts. +# +# Defaults to false. +# +#inhibit_user_in_use_error: true + + +## Metrics ### + +# Enable collection and rendering of performance metrics +# +#enable_metrics: false + +# Enable sentry integration +# NOTE: While attempts are made to ensure that the logs don't contain +# any sensitive information, this cannot be guaranteed. By enabling +# this option the sentry server may therefore receive sensitive +# information, and it in turn may then diseminate sensitive information +# through insecure notification channels if so configured. +# +#sentry: +# dsn: "..." + +# Flags to enable Prometheus metrics which are not suitable to be +# enabled by default, either for performance reasons or limited use. +# +metrics_flags: + # Publish synapse_federation_known_servers, a gauge of the number of + # servers this homeserver knows about, including itself. May cause + # performance problems on large homeservers. + # + #known_servers: true + +# Whether or not to report anonymized homeserver usage statistics. +# +#report_stats: true|false + +# The endpoint to report the anonymized homeserver usage statistics to. +# Defaults to https://matrix.org/report-usage-stats/push +# +#report_stats_endpoint: https://example.com/report-usage-stats/push + + +## API Configuration ## + +# Controls for the state that is shared with users who receive an invite +# to a room +# +room_prejoin_state: + # By default, the following state event types are shared with users who + # receive invites to the room: + # + # - m.room.join_rules + # - m.room.canonical_alias + # - m.room.avatar + # - m.room.encryption + # - m.room.name + # - m.room.create + # - m.room.topic + # + # Uncomment the following to disable these defaults (so that only the event + # types listed in 'additional_event_types' are shared). Defaults to 'false'. + # + #disable_default_event_types: true + + # Additional state event types to share with users when they are invited + # to a room. + # + # By default, this list is empty (so only the default event types are shared). + # + #additional_event_types: + # - org.example.custom.event.type + +# We record the IP address of clients used to access the API for various +# reasons, including displaying it to the user in the "Where you're signed in" +# dialog. +# +# By default, when puppeting another user via the admin API, the client IP +# address is recorded against the user who created the access token (ie, the +# admin user), and *not* the puppeted user. +# +# Uncomment the following to also record the IP address against the puppeted +# user. (This also means that the puppeted user will count as an "active" user +# for the purpose of monthly active user tracking - see 'limit_usage_by_mau' etc +# above.) +# +#track_puppeted_user_ips: true + + +# A list of application service config files to use +# +#app_service_config_files: +# - app_service_1.yaml +# - app_service_2.yaml + +# Uncomment to enable tracking of application service IP addresses. Implicitly +# enables MAU tracking for application service users. +# +#track_appservice_user_ips: true + + +# a secret which is used to sign access tokens. If none is specified, +# the registration_shared_secret is used, if one is given; otherwise, +# a secret key is derived from the signing key. +# +#macaroon_secret_key: + +# a secret which is used to calculate HMACs for form values, to stop +# falsification of values. Must be specified for the User Consent +# forms to work. +# +#form_secret: + +## Signing Keys ## + +# Path to the signing key to sign messages with +# +signing_key_path: "CONFDIR/SERVERNAME.signing.key" + +# The keys that the server used to sign messages with but won't use +# to sign new messages. +# +old_signing_keys: + # For each key, `key` should be the base64-encoded public key, and + # `expired_ts`should be the time (in milliseconds since the unix epoch) that + # it was last used. + # + # It is possible to build an entry from an old signing.key file using the + # `export_signing_key` script which is provided with synapse. + # + # For example: + # + #"ed25519:id": { key: "base64string", expired_ts: 123456789123 } + +# How long key response published by this server is valid for. +# Used to set the valid_until_ts in /key/v2 APIs. +# Determines how quickly servers will query to check which keys +# are still valid. +# +#key_refresh_interval: 1d + +# The trusted servers to download signing keys from. +# +# When we need to fetch a signing key, each server is tried in parallel. +# +# Normally, the connection to the key server is validated via TLS certificates. +# Additional security can be provided by configuring a `verify key`, which +# will make synapse check that the response is signed by that key. +# +# This setting supercedes an older setting named `perspectives`. The old format +# is still supported for backwards-compatibility, but it is deprecated. +# +# 'trusted_key_servers' defaults to matrix.org, but using it will generate a +# warning on start-up. To suppress this warning, set +# 'suppress_key_server_warning' to true. +# +# Options for each entry in the list include: +# +# server_name: the name of the server. required. +# +# verify_keys: an optional map from key id to base64-encoded public key. +# If specified, we will check that the response is signed by at least +# one of the given keys. +# +# accept_keys_insecurely: a boolean. Normally, if `verify_keys` is unset, +# and federation_verify_certificates is not `true`, synapse will refuse +# to start, because this would allow anyone who can spoof DNS responses +# to masquerade as the trusted key server. If you know what you are doing +# and are sure that your network environment provides a secure connection +# to the key server, you can set this to `true` to override this +# behaviour. +# +# An example configuration might look like: +# +#trusted_key_servers: +# - server_name: "my_trusted_server.example.com" +# verify_keys: +# "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr" +# - server_name: "my_other_trusted_server.example.com" +# +trusted_key_servers: + - server_name: "matrix.org" + +# Uncomment the following to disable the warning that is emitted when the +# trusted_key_servers include 'matrix.org'. See above. +# +#suppress_key_server_warning: true + +# 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. +# +#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 +# * password_config.enabled +# +# You will also want to investigate the settings under the "sso" configuration +# section below. + +# Enable SAML2 for registration and login. Uses pysaml2. +# +# At least one of `sp_config` or `config_path` must be set in this section to +# enable SAML login. +# +# Once SAML support is enabled, a metadata file will be exposed at +# https://:/_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://:/_synapse/client/saml2/authn_response. +# +saml2_config: + # `sp_config` is 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. + # + sp_config: + # 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. + # + #metadata: + # local: ["saml2/idp.xml"] + # remote: + # - url: https://our_idp/metadata.xml + + # Allowed clock difference in seconds between the homeserver and IdP. + # + # Uncomment the below to increase the accepted time difference from 0 to 3 seconds. + # + #accepted_time_diff: 3 + + # By default, the user has to go to our login page first. If you'd like + # to allow IdP-initiated login, set 'allow_unsolicited: true' in a + # 'service.sp' section: + # + #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 + + # Instead of putting the config inline as above, you can specify a + # separate pysaml2 configuration file: + # + #config_path: "CONFDIR/sp_conf.py" + + # 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. + # + #saml_session_lifetime: 5m + + # An external module can be provided here as a custom solution to + # mapping attributes returned from a saml provider onto a matrix user. + # + user_mapping_provider: + # The custom module's class. Uncomment to use a custom module. + # + #module: mapping_provider.SamlMappingProvider + + # Custom configuration values for the module. Below options are + # intended for the built-in provider, they should be changed if + # using a custom module. This section will be passed as a Python + # dictionary to the module's `parse_config` method. + # + config: + # The SAML attribute (after mapping via the attribute maps) to use + # to derive the Matrix ID from. '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_source_attribute: displayName + + # The mapping system to use for mapping the saml attribute onto a + # matrix ID. + # + # Options include: + # * 'hexencode' (which maps unpermitted characters to '=xx') + # * '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. + # + #mxid_mapping: dotreplace + + # 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'. + # + #grandfathered_mxid_source_attribute: upn + + # 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 below. All of the listed attributes must + # match for the login to be permitted. + # + #attribute_requirements: + # - attribute: userGroup + # value: "staff" + # - attribute: department + # value: "sales" + + # 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. + # + #idp_entityid: 'https://our_idp/entityid' + + +# List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration +# and login. +# +# 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:///. (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 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'. +# +# 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'. +# +# 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. +# +# 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 https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#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_claim: name of the claim containing a unique identifier +# for the user. Defaults to 'sub', which OpenID Connect +# compliant providers should provide. +# +# 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 'sso_auth_account_details.html' in the 'sso' +# section of this file). +# +# 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. +# +# 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 below. 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 +# below, the `family_name` claim MUST be "Stephensson", but the `groups` +# claim MUST contain "admin". +# +# attribute_requirements: +# - attribute: family_name +# value: "Stephensson" +# - attribute: groups +# value: "admin" +# +# See https://matrix-org.github.io/synapse/latest/openid.html +# 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.) +# +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 + # 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" + + +# Enable Central Authentication Service (CAS) for registration and login. +# +cas_config: + # Uncomment the following to enable authorization against a CAS server. + # Defaults to false. + # + #enabled: true + + # The URL of the CAS authorization endpoint. + # + #server_url: "https://cas-server.com" + + # The attribute of the CAS response to use as the display name. + # + # If unset, no displayname will be set. + # + #displayname_attribute: name + + # It is possible to configure Synapse to only allow logins if CAS attributes + # match particular values. All of the keys in the mapping 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. + # + #required_attributes: + # userGroup: "staff" + # department: None + + +# 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 +# https://matrix-org.github.io/synapse/latest/templates.html for more information. +# +sso: + # 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. + # + #client_whitelist: + # - https://riot.im/develop + # - https://my.custom.client/ + + # Uncomment 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. + # + #update_profile_information: true + + +# 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 https://matrix-org.github.io/synapse/latest/jwt.html. +# +#jwt_config: + # Uncomment the following to enable authorization using JSON web + # tokens. Defaults to false. + # + #enabled: true + + # 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 true. + # + #secret: "provided-by-your-issuer" + + # The algorithm used to sign the JSON web token. + # + # Supported algorithms are listed at + # https://pyjwt.readthedocs.io/en/latest/algorithms.html + # + # Required if 'enabled' is true. + # + #algorithm: "provided-by-your-issuer" + + # Name of the claim containing a unique identifier for the user. + # + # Optional, defaults to `sub`. + # + #subject_claim: "sub" + + # The issuer to validate the "iss" claim against. + # + # Optional, if provided the "iss" claim will be required and + # validated for all JSON web tokens. + # + #issuer: "provided-by-your-issuer" + + # 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. + # + #audiences: + # - "provided-by-your-issuer" + + +password_config: + # Uncomment to disable password login + # + #enabled: false + + # Uncomment 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. + # + #localdb_enabled: false + + # Uncomment and change to a secret random string for extra security. + # DO NOT CHANGE THIS AFTER INITIAL SETUP! + # + #pepper: "EVEN_MORE_SECRET" + + # Define and enforce a password policy. Each parameter is optional. + # This is an implementation of MSC2000. + # + policy: + # Whether to enforce the password policy. + # Defaults to 'false'. + # + #enabled: true + + # Minimum accepted length for a password. + # Defaults to 0. + # + #minimum_length: 15 + + # Whether a password must contain at least one digit. + # Defaults to 'false'. + # + #require_digit: true + + # 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_symbol: true + + # Whether a password must contain at least one lowercase letter. + # Defaults to 'false'. + # + #require_lowercase: true + + # Whether a password must contain at least one uppercase letter. + # Defaults to 'false'. + # + #require_uppercase: true + +ui_auth: + # The amount of time to allow a user-interactive authentication session + # to be active. + # + # This defaults to 0, meaning the user is queried for their credentials + # before every action, but this can be overridden to allow a single + # validation to be re-used. This weakens the protections afforded by + # the user-interactive authentication process, by allowing for multiple + # (and potentially different) operations to use the same validation session. + # + # This is ignored for potentially "dangerous" operations (including + # deactivating an account, modifying an account password, and + # adding a 3PID). + # + # Uncomment below to allow for credential validation to last for 15 + # seconds. + # + #session_timeout: "15s" + + +# Configuration for sending emails from Synapse. +# +# Server admins can configure custom templates for email content. See +# https://matrix-org.github.io/synapse/latest/templates.html for more information. +# +email: + # The hostname of the outgoing SMTP server to use. Defaults to 'localhost'. + # + #smtp_host: mail.server + + # The port on the mail server for outgoing SMTP. Defaults to 25. + # + #smtp_port: 587 + + # Username/password for authentication to the SMTP server. By default, no + # authentication is attempted. + # + #smtp_user: "exampleusername" + #smtp_pass: "examplepassword" + + # Uncomment the following to require TLS transport security for SMTP. + # By default, Synapse will connect over plain text, and will then switch to + # TLS via STARTTLS *if the SMTP server supports it*. If this option is set, + # Synapse will refuse to connect unless the server supports STARTTLS. + # + #require_transport_security: true + + # Uncomment the following to disable TLS for SMTP. + # + # By default, if the server supports TLS, it will be used, and the server + # must present a certificate that is valid for 'smtp_host'. If this option + # is set to false, TLS will not be used. + # + #enable_tls: false + + # notif_from defines the "From" address to use when sending emails. + # It must be set if email sending is enabled. + # + # The placeholder '%(app)s' will be replaced by the application name, + # which is normally 'app_name' (below), but may be overridden by the + # Matrix client application. + # + # Note that the placeholder must be written '%(app)s', including the + # trailing 's'. + # + #notif_from: "Your Friendly %(app)s homeserver " + + # app_name defines the default value for '%(app)s' in notif_from and email + # subjects. It defaults to 'Matrix'. + # + #app_name: my_branded_matrix_server + + # Uncomment the following to enable sending emails for messages that the user + # has missed. Disabled by default. + # + #enable_notifs: true + + # Uncomment the following to disable automatic subscription to email + # notifications for new users. Enabled by default. + # + #notif_for_new_users: false + + # Custom URL for client links within the email notifications. By default + # links will be based on "https://matrix.to". + # + # (This setting used to be called riot_base_url; the old name is still + # supported for backwards-compatibility but is now deprecated.) + # + #client_base_url: "http://localhost/riot" + + # Configure the time that a validation email will expire after sending. + # Defaults to 1h. + # + #validation_token_lifetime: 15m + + # The web client location to direct users to during an invite. This is passed + # to the identity server as the org.matrix.web_client_location key. Defaults + # to unset, giving no guidance to the identity server. + # + #invite_client_location: https://app.element.io + + # Subjects to use when sending emails from Synapse. + # + # The placeholder '%(app)s' will be replaced with the value of the 'app_name' + # setting above, or by a value dictated by the Matrix client application. + # + # If a subject isn't overridden in this configuration file, the value used as + # its example will be used. + # + #subjects: + + # Subjects for notification emails. + # + # On top of the '%(app)s' placeholder, these can use the following + # placeholders: + # + # * '%(person)s', which will be replaced by the display name of the user(s) + # that sent the message(s), e.g. "Alice and Bob". + # * '%(room)s', which will be replaced by the name of the room the + # message(s) have been sent to, e.g. "My super room". + # + # See the example provided for each setting to see which placeholder can be + # used and how to use them. + # + # Subject to use to notify about one message from one or more user(s) in a + # room which has a name. + #message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..." + # + # Subject to use to notify about one message from one or more user(s) in a + # room which doesn't have a name. + #message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..." + # + # Subject to use to notify about multiple messages from one or more users in + # a room which doesn't have a name. + #messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..." + # + # Subject to use to notify about multiple messages in a room which has a + # name. + #messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..." + # + # Subject to use to notify about multiple messages in multiple rooms. + #messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..." + # + # Subject to use to notify about multiple messages from multiple persons in + # multiple rooms. This is similar to the setting above except it's used when + # the room in which the notification was triggered has no name. + #messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..." + # + # Subject to use to notify about an invite to a room which has a name. + #invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..." + # + # Subject to use to notify about an invite to a room which doesn't have a + # name. + #invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..." + + # Subject for emails related to account administration. + # + # On top of the '%(app)s' placeholder, these one can use the + # '%(server_name)s' placeholder, which will be replaced by the value of the + # 'server_name' setting in your Synapse configuration. + # + # Subject to use when sending a password reset email. + #password_reset: "[%(server_name)s] Password reset" + # + # Subject to use when sending a verification email to assert an address's + # ownership. + #email_validation: "[%(server_name)s] Validate your email" + + + +## Push ## + +push: + # 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 former, this option controls whether the + # notification request includes the content of the event (other details + # like the sender are still included). For `event_id_only` push, 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. + # + # The default value is "true" to include message details. Uncomment to only + # include the event ID and room ID in push notification payloads. + # + #include_content: 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. + # + # The default value is "true", meaning push clients will see the number of + # rooms with unread messages in them. Uncomment to instead send the number + # of unread messages. + # + #group_unread_count_by_room: false + + +## Rooms ## + +# 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. +# +#encryption_enabled_by_default_for_room_type: invite + + +# Uncomment to allow non-server-admin users to create groups on this server +# +#enable_group_creation: true + +# If enabled, non server admins can only create groups with local parts +# starting with this prefix +# +#group_creation_prefix: "unofficial_" + + + +# User Directory configuration +# +user_directory: + # Defines whether users can search the user directory. If false then + # empty responses are returned to all queries. Defaults to true. + # + # Uncomment to disable the user directory. + # + #enabled: false + + # Defines whether to search all users visible to your HS when searching + # the user directory. 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 API following the instructions at + # https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#run + # + # Uncomment to return search results containing all known users, even if that + # user does not share a room with the requester. + # + #search_all_users: true + + # Defines whether to prefer local users in search query results. + # If True, local users are more likely to appear above remote users + # when searching the user directory. Defaults to false. + # + # Uncomment to prefer local over remote users in user directory search + # results. + # + #prefer_local_users: true + + +# User Consent configuration +# +# for detailed instructions, see +# https://matrix-org.github.io/synapse/latest/consent_tracking.html +# +# Parts of this section are required if enabling the 'consent' resource under +# '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 +# '.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 +# 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". +# +#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 +# + + + +# Settings for local room and user statistics collection. See +# https://matrix-org.github.io/synapse/latest/room_and_user_statistics.html. +# +stats: + # Uncomment the following to disable room and user statistics. Note that doing + # so may cause certain features (such as the room directory) not to work + # correctly. + # + #enabled: false + + +# Server Notices room configuration +# +# Uncomment this section to enable a room which can be used to send notices +# from the server to users. It is a special room which cannot be left; notices +# come from a special "notices" user id. +# +# If you uncomment this section, you *must* define the system_mxid_localpart +# setting, which defines the id of the user which will be used to send the +# notices. +# +# It's also possible to override the room name, the display name of the +# "notices" user, and the avatar for the user. +# +#server_notices: +# system_mxid_localpart: notices +# system_mxid_display_name: "Server Notices" +# system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" +# room_name: "Server Notices" + + + +# Uncomment 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. +# +#enable_room_list_search: false + +# The `alias_creation` option controls who's 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 +# alias: Matches against the alias being created +# room_id: Matches against the room ID the alias is being pointed at +# action: Whether to "allow" or "deny" the request if the rule matches +# +# The default is: +# +#alias_creation_rules: +# - user_id: "*" +# alias: "*" +# room_id: "*" +# action: allow + +# 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 +# room_id: Matches against the room ID being published +# alias: Matches against any current local or canonical aliases +# associated with the room +# action: Whether to "allow" or "deny" the request if the rule matches +# +# The default is: +# +#room_list_publication_rules: +# - user_id: "*" +# alias: "*" +# room_id: "*" +# action: allow + + +## Opentracing ## + +# These settings enable 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 other services which supports opentracing +# (specifically those implemented with Jaeger). +# +opentracing: + # tracing is disabled by default. Uncomment the following line to enable it. + # + #enabled: true + + # The list of homeservers we wish to send and receive span contexts and span baggage. + # See https://matrix-org.github.io/synapse/latest/opentracing.html. + # + # 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. + # + #homeserver_whitelist: + # - ".*" + + # 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. + # + #force_tracing_for_users: + # - "@user1:server_name" + # - "@user2:server_name" + + # 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/. + # + #jaeger_config: + # sampler: + # type: const + # param: 1 + # logging: + # false + + +## Workers ## + +# Disables sending of outbound federation transactions on the main process. +# Uncomment if using a federation sender worker. +# +#send_federation: false + +# It is possible to run multiple federation sender workers, in which case the +# work is balanced across them. +# +# This configuration must be shared between all federation sender workers, and if +# changed all federation sender workers must be stopped at the same time and then +# started, to ensure that all instances are running with the same config (otherwise +# events may be dropped). +# +#federation_sender_instances: +# - federation_sender1 + +# When using workers this should be a map from `worker_name` to the +# HTTP replication listener of the worker, if configured. +# +#instance_map: +# worker1: +# host: localhost +# port: 8034 + +# Experimental: When using workers you can define which workers should +# handle event persistence and typing notifications. Any worker +# specified here must also be in the `instance_map`. +# +#stream_writers: +# events: worker1 +# typing: worker1 + +# The worker that is used to run background tasks (e.g. cleaning up expired +# data). If not provided this defaults to the main process. +# +#run_background_tasks_on: worker1 + +# A shared secret used by the replication APIs to authenticate HTTP requests +# from workers. +# +# By default this is unused and traffic is not authenticated. +# +#worker_replication_secret: "" + + +# Configuration for Redis when using workers. This *must* be enabled when +# using workers (unless using old style direct TCP configuration). +# +redis: + # Uncomment the below to enable Redis support. + # + #enabled: true + + # Optional host and port to use to connect to redis. Defaults to + # localhost and 6379 + # + #host: localhost + #port: 6379 + + # Optional password if configured on the Redis instance + # + #password: + From 08e3efa4b43a457a1abc89f001d588e93e49e42a Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Thu, 24 Feb 2022 09:51:48 -0800 Subject: [PATCH 02/11] more work on docs --- .../configuration/config_documentation.md | 1661 ++++++++++------- 1 file changed, 981 insertions(+), 680 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index d11c3a0fb24d..6b5d6a86cb95 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -1,7 +1,7 @@ ## Welcome This is intended as a guide to the synapse configuration-each config option is documented, including instructions -on how to change the default and what sort of behavior to expect if the default is changed, and an example +on how to change the default and what sort of behavior to expect if the default is changed. Also included is an example configuration. If you don't want to spend a lot of time thinking about options, the config as generated sets sensible defaults for most values. [which values must you fill in? server name, ports?, public base url?] @@ -9,17 +9,25 @@ for most values. [which values must you fill in? server name, ports?, public bas 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 + +For example, setting `redaction_retention_period: 5m` would remove redacted messages from the database after 5 minutes, rather than 5 months. ## List of config options in the order in which they are found in the real config +--- Config option: `modules` Server admins can expand Synapse's functionality with external modules. @@ -501,177 +509,248 @@ max_mau_value: 50 --- Config option: `mau_trial_days` -# 'mau_trial_days' is a means to add a grace period for active users. It -# means that users must be active for this 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. -# -# '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 -# -#limit_usage_by_mau: false -#max_mau_value: 50 -#mau_trial_days: 2 -#mau_limit_alerting: false +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. -# If enabled, the metrics for the number of monthly active users will -# be populated, however no one will be limited. If limit_usage_by_mau -# is true, this is implied to be true. -# -#mau_stats_only: false +Example configuration: +``` +mau_trial_days: 5 +``` +--- +Config option: `mau_limit_alerting` -# Sometimes the server admin will want to ensure certain accounts are -# never blocked by mau checking. These accounts are specified here. -# -#mau_limit_reserved_threepids: -# - medium: 'email' -# address: 'reserved_user@example.com' +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. -# Used by phonehome stats to group together related servers. -#server_context: context +Example configuration: +``` +mau_limit_alerting: false +``` +--- +Config option: `mau_stats_only` -# Resource-constrained homeserver settings -# -# When this 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. -# -# Room complexity is an arbitrary measure based on factors such as the number of -# users in the room. -# +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. Uncomment and add users to enable. + +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. Uncomment and add a context to enable. + +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. Uncomment to set the options as illustrated below. + +Room complexity is an arbitrary measure based on factors such as the number of +users in the room. + +Example configuration: +``` limit_remote_rooms: - # Uncomment to enable room complexity checking. - # - #enabled: true + # Enables room complexity checking. + enabled: true # the limit above which rooms cannot be joined. The default is 1.0. - # - #complexity: 0.5 + complexity: 0.5 # override the error which is returned when the room is too complex. - # - #complexity_error: "This room is too complex." + complexity_error: "This room is too complex." # allow server admins to join complex rooms. Default is false. - # - #admins_can_join: true + 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'. -# -#require_membership_for_aliases: false +Whether to require a user to be in the room to add an alias to it. +Defaults to 'true'. -# Whether to allow per-room membership profiles through the send of membership -# events with profile information that differ from the target's global profile. -# Defaults to 'true'. -# -#allow_per_room_profiles: false +Example configuration: +``` +require_membership_for_aliases: false +``` +--- +Config option: `allow_per_room_profiles` -# The largest allowed file size for a user avatar. Defaults to no restriction. -# -# Note that user avatar changes will not work if this is set without -# using Synapse's media repository. -# -#max_avatar_size: 10M +Whether to allow per-room membership profiles through the sending of membership +events with profile information that differs from the target's global profile. +Defaults to true. -# The MIME types allowed for user avatars. Defaults to no restriction. -# -# Note that user avatar changes will not work if this is set without -# using Synapse's media repository. -# -#allowed_avatar_mimetypes: ["image/png", "image/jpeg", "image/gif"] +Example configuration: +``` +allow_per_room_profiles: false +``` +--- +Config option: `max_avatar_size` -# How long to keep redacted events in unredacted form in the database. After -# this period redacted events get replaced with their redacted form in the DB. -# -# Defaults to `7d`. Set to `null` to disable. -# -#redaction_retention_period: 28d +The largest permissible file size in bytes for a user avatar. Defaults to no restriction. +Use M for MB and K for KB. -# How long to track users' last seen time and IPs in the database. -# -# Defaults to `28d`. Set to `null` to disable clearing out of old rows. -# -#user_ips_max_age: 14d +Note that user avatar changes will not work if this is set without using Synapse's media repository. -# Inhibits the /requestToken endpoints from returning an error that might leak -# information about whether an e-mail address is in use or not on this -# homeserver. -# Note that for some endpoints the error situation is the e-mail already being -# used, and for others the error is entering the e-mail being unused. -# If this option is enabled, instead of returning an error, these endpoints will -# act as if no error happened and return a fake session ID ('sid') to clients. -# -#request_token_inhibit_3pid_errors: true +Example configuration: +``` +max_avatar_size: 10M +``` +--- +Config option: `allowed_avatar_mimetypes` -# A list of domains that the domain portion of 'next_link' parameters -# must match. -# -# This parameter is optionally provided by clients while requesting -# validation of an email or phone number, and maps to a link that -# users will be automatically redirected to after validation -# succeeds. Clients can make use this parameter to aid the validation -# process. -# -# The whitelist is applied whether the homeserver or an -# identity server is handling validation. -# -# The default value is no whitelist functionality; all domains are -# allowed. Setting this value to an empty list will instead disallow -# all domains. -# -#next_link_domain_whitelist: ["matrix.org"] +The MIME types allowed for user avatars. Defaults to no restriction. -# Templates to use when generating email or HTML page contents. -# + +Note that user avatar changes will not work if this is set without +using Synapse's media repository. + +Example configuration: +``` +allowed_avatar_mimetypes: ["image/png", "image/jpeg", "image/gif"] +``` +--- +Config option: `redaction_retention_period` + +How long to keep redacted events in unredacted form in the database. After +this period redacted events get replaced with their redacted form in the DB. + +Defaults to `7d`. Uncomment and set to `null` to disable. + +Example configuration: +``` +redaction_retention_period: 28d +``` +--- +Config option: `user_ips_max_age` + +How long to track users' last seen time and IPs in the database. + +Defaults to `28d`. Uncomment and set to `null` to disable clearing out of old rows. + +Example configuration: +``` +user_ips_max_age: 14d +``` +--- +Config option: `request_token_inhibit_3pid_errors` + +Inhibits the /requestToken endpoints from returning an error that might leak +information about whether an e-mail address is in use or not on this +homeserver. Defaults to false. +Note that for some endpoints the error situation is the e-mail already being +used, and for others the error is entering the e-mail being unused. +If this option is enabled, instead of returning an error, these endpoints will +act as if no error happened and return a fake session ID ('sid') to clients. + +Example configuration: +``` +request_token_inhibit_3pid_errors: true +``` +--- +Config option: `next_link_domain_whitelist` + +A list of domains that the domain portion of 'next_link' parameters +must match. + +This parameter is optionally provided by clients while requesting +validation of an email or phone number, and maps to a link that +users will be automatically redirected to after validation +succeeds. Clients can make use this parameter to aid the validation +process. + +The whitelist is applied whether the homeserver or an identity server is handling validation. + +The default value is no whitelist functionality; all domains are +allowed. Setting this value to an empty list will instead disallow +all domains. + +Example configuration: +``` +next_link_domain_whitelist: ["matrix.org"] +``` +--- +Config option: `templates` and `custom_template_directory` + +Templates to use when generating email or HTML page contents. The `custom_template_directory` +determines which directory Synapse will try to find template files in to use to generate email or HTML page contents. +If not set, or a file is not found within the template directory, a default +template from within the Synapse package will be used. + +See https://matrix-org.github.io/synapse/latest/templates.html for more +information about using custom templates. + +Example configuration: +``` templates: - # Directory in which Synapse will try to find template files to use to generate - # email or HTML page contents. - # If not set, or a file is not found within the template directory, a default - # template from within the Synapse package will be used. - # - # See https://matrix-org.github.io/synapse/latest/templates.html for more - # information about using custom templates. - # - #custom_template_directory: /path/to/custom/templates/ + custom_template_directory: /path/to/custom/templates/ +``` +--- +Config option: `retention` +This option and the associated options determine message retention policy at the +server level. -# Message retention policy at the server level. -# -# Room admins and mods can define a retention period for their rooms using the -# 'm.room.retention' state event, and server admins can cap this period by setting -# the 'allowed_lifetime_min' and 'allowed_lifetime_max' config options. -# -# If this feature is enabled, Synapse will regularly look for and purge events -# which are older than the room's maximum retention period. Synapse will also -# filter events received over federation so that events that should have been -# purged are ignored and not stored again. -# +Room admins and mods can define a retention period for their rooms using the +`m.room.retention` state event, and server admins can cap this period by setting +the `allowed_lifetime_min` and `allowed_lifetime_max` config options. + +If this feature is enabled, Synapse will regularly look for and purge events +which are older than the room's maximum retention period. Synapse will also +filter events received over federation so that events that should have been +purged are ignored and not stored again. + +The message retention policies feature is disabled by default. + +Example configuration: +``` retention: - # The message retention policies feature is disabled by default. Uncomment the - # following line to enable it. - # - #enabled: true + enabled: true # Default retention policy. If set, Synapse will apply it to rooms that lack the # 'm.room.retention' state event. Currently, the value of 'min_lifetime' doesn't # matter much because Synapse doesn't take it into account yet. # - #default_policy: - # min_lifetime: 1d - # max_lifetime: 1y + default_policy: + min_lifetime: 1d + max_lifetime: 1y # Retention policy limits. If set, and the state of a room contains a # 'm.room.retention' event in its state which contains a 'min_lifetime' or a # 'max_lifetime' that's out of these bounds, Synapse will cap the room's policy # to these limits when running purge jobs. - # - #allowed_lifetime_min: 1d - #allowed_lifetime_max: 1y + + allowed_lifetime_min: 1d + allowed_lifetime_max: 1y # Server admins can define the settings of the background jobs purging the # events which lifetime has expired under the 'purge_jobs' section. @@ -702,124 +781,173 @@ retention: # room's policy to these values is done after the policies are retrieved from # Synapse's database (which is done using the range specified in a purge job's # configuration). - # - #purge_jobs: - # - longest_max_lifetime: 3d - # interval: 12h - # - shortest_max_lifetime: 3d - # interval: 1d + + purge_jobs: + - longest_max_lifetime: 3d + interval: 12h + - shortest_max_lifetime: 3d + interval: 1d +``` +--- +Config option: `tls_certificate_path` +This option specifies a PEM-encoded X509 certificate for TLS. +This certificate, as of Synapse 1.0, will need to be a valid and verifiable +certificate, signed by a recognised Certificate Authority. -## TLS ## +Be sure to use a `.pem` file that includes the full certificate chain including +any intermediate certificates (for instance, if using certbot, use +`fullchain.pem` as your certificate, not `cert.pem`). -# PEM-encoded X509 certificate for TLS. -# This certificate, as of Synapse 1.0, will need to be a valid and verifiable -# certificate, signed by a recognised Certificate Authority. -# -# Be sure to use a `.pem` file that includes the full certificate chain including -# any intermediate certificates (for instance, if using certbot, use -# `fullchain.pem` as your certificate, not `cert.pem`). -# -#tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" +Example configuration: +``` +tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" +``` +--- +Config option: `tls_private_key_path` -# PEM-encoded private key for TLS -# -#tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" +PEM-encoded private key for TLS. -# Whether to verify TLS server certificates for outbound federation requests. -# -# Defaults to `true`. To disable certificate verification, uncomment the -# following line. -# -#federation_verify_certificates: false +Example configuration: +``` +tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" +``` +--- +Config option: `federation_verify_certificates` +Whether to verify TLS server certificates for outbound federation requests. -# The minimum TLS version that will be used for outbound federation requests. -# -# Defaults to `1`. Configurable to `1`, `1.1`, `1.2`, or `1.3`. Note -# that setting this value higher than `1.2` will prevent federation to most -# of the public Matrix network: only configure it to `1.3` if you have an -# entirely private federation setup and you can ensure TLS 1.3 support. -# -#federation_client_minimum_tls_version: 1.2 +Defaults to `true`. To disable certificate verification, uncomment the option. -# Skip federation certificate verification on the following whitelist -# of domains. -# -# This setting should only be used in very specific cases, such as -# federation over Tor hidden services and similar. For private networks -# of homeservers, you likely want to use a private CA instead. -# -# Only effective if federation_verify_certicates is `true`. -# -#federation_certificate_verification_whitelist: -# - lon.example.com -# - "*.domain.com" -# - "*.onion" +Example configuration: +``` +federation_verify_certificates: false +``` +--- +Config option: `federation_client_minimum_tls_version` -# List of custom certificate authorities for federation traffic. -# -# This setting should only normally be used within a private network of -# homeservers. -# -# Note that this list will replace those that are provided by your -# operating environment. Certificates must be in PEM format. -# -#federation_custom_ca_list: -# - myCA1.pem -# - myCA2.pem -# - myCA3.pem +The minimum TLS version that will be used for outbound federation requests. +Defaults to `1`. Configurable to `1`, `1.1`, `1.2`, or `1.3`. Note +that setting this value higher than `1.2` will prevent federation to most +of the public Matrix network: only configure it to `1.3` if you have an +entirely private federation setup and you can ensure TLS 1.3 support. -## Federation ## +Example configuration: +``` +federation_client_minimum_tls_version: 1.2 +``` +--- +Config option: `federation_certificate_verification_whitelist` -# Restrict federation to the following whitelist of domains. -# N.B. we recommend also firewalling your federation listener to limit -# inbound federation traffic as early as possible, rather than relying -# purely on this application-layer restriction. If not specified, the -# default is to whitelist everything. -# -#federation_domain_whitelist: -# - lon.example.com -# - nyc.example.com -# - syd.example.com +Skip federation certificate verification on a given whitelist +of domains. -# Report prometheus metrics on the age of PDUs being sent to and received from -# the following domains. This can be used to give an idea of "delay" on inbound -# and outbound federation, though be aware that any delay can be due to problems -# at either end or with the intermediate network. -# -# By default, no domains are monitored in this way. -# -#federation_metrics_domains: -# - matrix.org -# - example.com +This setting should only be used in very specific cases, such as +federation over Tor hidden services and similar. For private networks +of homeservers, you likely want to use a private CA instead. -# Uncomment to disable profile lookup over federation. By default, the -# Federation API allows other homeservers to obtain profile data of any user -# on this homeserver. Defaults to 'true'. -# -#allow_profile_lookup_over_federation: false +Only effective if `federation_verify_certicates` is `true`. -# Uncomment to disable device display name lookup over federation. By default, the -# Federation API allows other homeservers to obtain device display names of any user -# on this homeserver. Defaults to 'true'. -# -#allow_device_name_lookup_over_federation: false +Example configuration: +``` +federation_certificate_verification_whitelist: + - lon.example.com + - "*.domain.com" + - "*.onion" +``` +--- +Config option: `federation_custom_ca_list` +List of custom certificate authorities for federation traffic. -## Caching ## +This setting should only normally be used within a private network of +homeservers. -# Caching can be configured through the following options. -# -# A cache 'factor' is a multiplier that can be applied to each of -# Synapse's caches in order to increase or decrease the maximum -# number of entries that can be stored. +Note that this list will replace those that are provided by your +operating environment. Certificates must be in PEM format. -# The number of events to cache in memory. Not affected by -# caches.global_factor. -# -#event_cache_size: 10K +Example configuration: +``` +federation_custom_ca_list: + - myCA1.pem + - myCA2.pem + - myCA3.pem +``` +--- +Config option: `federation_domain_whitelist` + +Restrict federation to the given whitelist of domains. +N.B. we recommend also firewalling your federation listener to limit +inbound federation traffic as early as possible, rather than relying +purely on this application-layer restriction. If not specified, the +default is to whitelist everything. + +Example configuration: +``` +federation_domain_whitelist: + - lon.example.com + - nyc.example.com + - syd.example.com +``` +--- +Config option: `federation_metrics_domains` + +Report prometheus metrics on the age of PDUs being sent to and received from +the given domains. This can be used to give an idea of "delay" on inbound +and outbound federation, though be aware that any delay can be due to problems +at either end or with the intermediate network. + +By default, no domains are monitored in this way. +Example configuration: +``` +federation_metrics_domains: + - matrix.org + - example.com +``` +--- +Config option: `allow_profile_lookup_over_federation` + +Uncomment to disable profile lookup over federation. By default, the +Federation API allows other homeservers to obtain profile data of any user +on this homeserver. Defaults to 'true'. + +Example configuration: +``` +allow_profile_lookup_over_federation: false +``` +--- +Config option: `allow_device_name_lookup_over_federation` + +Uncomment this option to disable device display name lookup over federation. By default, the +Federation API allows other homeservers to obtain device display names of any user +on this homeserver. Defaults to 'true'. + +Example configuration: +``` +allow_device_name_lookup_over_federation: false +``` +--- +Config option: `event_cache_size` + +The number of events to cache in memory. Not affected by +`caches.global_factor`. + +Example configuration: +``` +event_cache_size: 10K +``` +--- +Config option: `cache` and associated values + +Caching can be configured through the following options. + +A cache 'factor' is a multiplier that can be applied to each of +Synapse's caches in order to increase or decrease the maximum +number of entries that can be stored. + +Example configuration: +``` caches: # Controls the global cache factor, which is the default cache factor # for all caches if a specific factor for that cache is not otherwise @@ -831,7 +959,7 @@ caches: # # Defaults to 0.5, which will half the size of all caches. # - #global_factor: 1.0 + global_factor: 1.0 # A dictionary of cache name to cache factor for that individual # cache. Overrides the global cache factor for a given cache. @@ -849,13 +977,13 @@ caches: # variable would be `SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0`. # per_cache_factors: - #get_users_who_share_room_with_user: 2.0 + get_users_who_share_room_with_user: 2.0 # Controls how long an entry can be in a cache without having been # accessed before being evicted. Defaults to None, which means # entries are never evicted based on time. # - #expiry_time: 30m + expiry_time: 30m # Controls how long the results of a /sync request are cached for after # a successful response is returned. A higher duration can help clients with @@ -864,476 +992,649 @@ caches: # By default, this is zero, which means that sync responses are not cached # at all. # - #sync_response_cache_duration: 2m + sync_response_cache_duration: 2m +``` +--- +Config option: `database` +The 'database' setting defines the database that synapse uses to store all of +its data. -## Database ## +'name' gives the database engine to use: either 'sqlite3' (for SQLite) or +'psycopg2' (for PostgreSQL). -# The 'database' setting defines the database that synapse uses to store all of -# its data. -# -# 'name' gives the database engine to use: either 'sqlite3' (for SQLite) or -# 'psycopg2' (for PostgreSQL). -# -# 'txn_limit' gives the maximum number of transactions to run per connection -# before reconnecting. Defaults to 0, which means no limit. -# -# 'args' gives options which are passed through to the database engine, -# except for options starting 'cp_', which are used to configure the Twisted -# connection pool. For a reference to valid arguments, see: -# * for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect -# * for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS -# * for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ -# -# -# Example SQLite configuration: -# -#database: -# name: sqlite3 -# args: -# database: /path/to/homeserver.db -# -# -# Example Postgres configuration: -# -#database: -# name: psycopg2 -# txn_limit: 10000 -# args: -# user: synapse_user -# password: secretpassword -# database: synapse -# host: localhost -# port: 5432 -# cp_min: 5 -# cp_max: 10 -# -# For more information on using Synapse with Postgres, -# see https://matrix-org.github.io/synapse/latest/postgres.html. -# +'txn_limit' gives the maximum number of transactions to run per connection +before reconnecting. Defaults to 0, which means no limit. + +'args' gives options which are passed through to the database engine, +except for options starting 'cp_', which are used to configure the Twisted +connection pool. For a reference to valid arguments, see: +* for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect +* for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS +* for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ + +For more information on using Synapse with Postgres, +see https://matrix-org.github.io/synapse/latest/postgres.html. + +Example SQLite configuration: +``` database: name: sqlite3 args: - database: DATADIR/homeserver.db + database: /path/to/homeserver.db +``` +Example Postgres configuration: +``` +database: + name: psycopg2 + txn_limit: 10000 + args: + user: synapse_user + password: secretpassword + database: synapse + host: localhost + port: 5432 + cp_min: 5 + cp_max: 10 +``` +--- +Config option: `log_config` -## Logging ## +A yaml python logging config file as described by +https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema -# A yaml python logging config file as described by -# https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema -# +Example configuration: +``` log_config: "CONFDIR/SERVERNAME.log.config" +``` +--- +# Ratelimiting +Each ratelimiting configuration is made of two parameters: + - per_second: number of requests a client can send per second. + - burst_count: number of requests a client can send before being throttled. +--- +Config option: `rc_message` -## Ratelimiting ## - -# Ratelimiting settings for client actions (registration, login, messaging). -# -# Each ratelimiting configuration is made of two parameters: -# - per_second: number of requests a client can send per second. -# - burst_count: number of requests a client can send before being throttled. -# -# Synapse currently uses the following configurations: -# - one for messages that ratelimits sending based on the account the client -# is using -# - one for registration that ratelimits registration requests based on the -# client's IP address. -# - one for checking the validity of registration tokens that ratelimits -# requests based on the client's IP address. -# - one for login that ratelimits login requests based on the client's IP -# address. -# - one for login that ratelimits login requests based on the account the -# client is attempting to log into. -# - one for login that ratelimits login requests based on the account the -# client is attempting to log into, based on the amount of failed login -# attempts for this account. -# - one for ratelimiting redactions by room admins. If this is not explicitly -# set then it uses the same ratelimiting as per rc_message. This is useful -# to allow room admins to deal with abuse quickly. -# - two for ratelimiting number of rooms a user can join, "local" for when -# users are joining rooms the server is already in (this is cheap) vs -# "remote" for when users are trying to join rooms not on the server (which -# can be more expensive) -# - one for ratelimiting how often a user or IP can attempt to validate a 3PID. -# - two for ratelimiting how often invites can be sent in a room or to a -# specific user. -# - one for ratelimiting 3PID invites (i.e. invites sent to a third-party ID -# such as an email address or a phone number) based on the account that's -# sending the invite. -# -# The defaults are as shown below. -# -#rc_message: -# per_second: 0.2 -# burst_count: 10 -# -#rc_registration: -# per_second: 0.17 -# burst_count: 3 -# -#rc_registration_token_validity: -# per_second: 0.1 -# burst_count: 5 -# -#rc_login: -# address: -# per_second: 0.17 -# burst_count: 3 -# account: -# per_second: 0.17 -# burst_count: 3 -# failed_attempts: -# per_second: 0.17 -# burst_count: 3 -# -#rc_admin_redaction: -# per_second: 1 -# burst_count: 50 -# -#rc_joins: -# local: -# per_second: 0.1 -# burst_count: 10 -# remote: -# per_second: 0.01 -# burst_count: 10 -# -#rc_3pid_validation: -# per_second: 0.003 -# burst_count: 5 -# -#rc_invites: -# per_room: -# per_second: 0.3 -# burst_count: 10 -# per_user: -# per_second: 0.003 -# burst_count: 5 -# -#rc_third_party_invite: -# per_second: 0.2 -# burst_count: 10 - -# Ratelimiting settings for incoming federation -# -# The rc_federation configuration is made up of the following settings: -# - window_size: window size in milliseconds -# - sleep_limit: number of federation requests from a single server in -# a window before the server will delay processing the request. -# - sleep_delay: duration in milliseconds to delay processing events -# from remote servers by if they go over the sleep limit. -# - reject_limit: maximum number of concurrent federation requests -# allowed from a single server -# - concurrent: number of federation requests to concurrently process -# from a single server -# -# The defaults are as shown below. -# -#rc_federation: -# window_size: 1000 -# sleep_limit: 10 -# sleep_delay: 500 -# reject_limit: 50 -# concurrent: 3 - -# Target outgoing federation transaction frequency for sending read-receipts, -# per-room. -# -# If we end up trying to send out more read-receipts, they will get buffered up -# into fewer transactions. -# -#federation_rr_transactions_per_room_per_second: 50 - - - -## Media Store ## - -# Enable the media store service in the Synapse master. Uncomment the -# following if you are using a separate media store worker. -# -#enable_media_repo: false - -# Directory where uploaded images and attachments are stored. -# -media_store_path: "DATADIR/media_store" - -# Media storage providers allow media to be stored in different -# locations. -# -#media_storage_providers: -# - module: file_system -# # Whether to store newly uploaded local files -# store_local: false -# # Whether to store newly downloaded remote files -# store_remote: false -# # Whether to wait for successful storage for local uploads -# store_synchronous: false -# config: -# directory: /mnt/some/other/directory - -# The largest allowed upload size in bytes -# -# If you are using a reverse proxy you may also need to set this value in -# your reverse proxy's config. Notably Nginx has a small max body size by default. -# See https://matrix-org.github.io/synapse/latest/reverse_proxy.html. -# -#max_upload_size: 50M - -# Maximum number of pixels that will be thumbnailed -# -#max_image_pixels: 32M - -# Whether to generate new thumbnails on the fly to precisely match -# the resolution requested by the client. If true then whenever -# a new resolution is requested by the client the server will -# generate a new thumbnail. If false the server will pick a thumbnail -# from a precalculated list. -# -#dynamic_thumbnails: false - -# List of thumbnails to precalculate when an image is uploaded. -# -#thumbnail_sizes: -# - width: 32 -# height: 32 -# method: crop -# - width: 96 -# height: 96 -# method: crop -# - width: 320 -# height: 240 -# method: scale -# - width: 640 -# height: 480 -# method: scale -# - width: 800 -# height: 600 -# method: scale - -# Is the preview URL API enabled? -# -# 'false' by default: uncomment the following to enable it (and specify a -# url_preview_ip_range_blacklist blacklist). -# -#url_preview_enabled: true - -# List of IP address CIDR ranges that the URL preview spider is denied -# from accessing. There are no defaults: you must explicitly -# specify a list for URL previewing to work. You should specify any -# internal services in your network that you do not want synapse to try -# to connect to, otherwise anyone in any Matrix room could cause your -# synapse to issue arbitrary GET requests to your internal services, -# causing serious security issues. -# -# (0.0.0.0 and :: are always blacklisted, whether or not they are explicitly -# listed here, since they correspond to unroutable addresses.) -# -# This must be specified if url_preview_enabled is set. It is recommended that -# you uncomment the following list as a starting point. -# -# Note: The value is ignored when an HTTP proxy is in use -# -#url_preview_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' - -# List of IP address CIDR ranges that the URL preview spider is allowed -# to access even if they are specified in url_preview_ip_range_blacklist. -# This is useful for specifying exceptions to wide-ranging blacklisted -# target IP ranges - e.g. for enabling URL previews for a specific private -# website only visible in your network. -# -#url_preview_ip_range_whitelist: -# - '192.168.1.1' - -# Optional list of URL matches that the URL preview spider is -# denied from accessing. You should use url_preview_ip_range_blacklist -# in preference to this, otherwise someone could define a public DNS -# entry that points to a private IP address and circumvent the blacklist. -# This is more useful if you know there is an entire shape of URL that -# you know that will never want synapse to try to spider. -# -# Each list entry is a dictionary of url component attributes as returned -# by urlparse.urlsplit as applied to the absolute form of the URL. See -# https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit -# The values of the dictionary are treated as an filename match pattern -# applied to that component of URLs, unless they start with a ^ in which -# case they are treated as a regular expression match. If all the -# specified component matches for a given list item succeed, the URL is -# blacklisted. -# -#url_preview_url_blacklist: -# # blacklist any URL with a username in its URI -# - username: '*' -# -# # blacklist all *.google.com URLs -# - netloc: 'google.com' -# - netloc: '*.google.com' -# -# # blacklist all plain HTTP URLs -# - scheme: 'http' -# -# # blacklist http(s)://www.acme.com/foo -# - netloc: 'www.acme.com' -# path: '/foo' -# -# # blacklist any URL with a literal IPv4 address -# - netloc: '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' - -# The largest allowed URL preview spidering size in bytes -# -#max_spider_size: 10M - -# A list of values for the Accept-Language HTTP header used when -# downloading webpages during URL preview generation. This allows -# Synapse to specify the preferred languages that URL previews should -# be in when communicating with remote servers. -# -# Each value is a IETF language tag; a 2-3 letter identifier for a -# language, optionally followed by subtags separated by '-', specifying -# a country or region variant. -# -# Multiple values can be provided, and a weight can be added to each by -# using quality value syntax (;q=). '*' translates to any language. -# -# Defaults to "en". -# -# Example: -# -# url_preview_accept_language: -# - en-UK -# - en-US;q=0.9 -# - fr;q=0.8 -# - *;q=0.7 -# -url_preview_accept_language: -# - en - - -# oEmbed allows for easier embedding content from a website. It can be -# used for generating URLs previews of services which support it. -# -oembed: - # A default list of oEmbed providers is included with Synapse. - # - # Uncomment the following to disable using these default oEmbed URLs. - # Defaults to 'false'. - # - #disable_default_providers: true +Ratelimiting settings for client messaging. + +This is a ratelimiting option for messages that ratelimits sending based on the account the client +is using. It defaults to: `per_second: 0.2`, `burst_count: 10`. Uncomment and set +to change the default. - # Additional files with oEmbed configuration (each should be in the - # form of providers.json). - # - # By default, this list is empty (so only the default providers.json - # is used). - # - #additional_providers: - # - oembed/my_providers.json +Example configuration: +``` +rc_message: + per_second: 0.5 + burst_count: 15 +``` +--- +Config option: `rc_registration` +This option ratelimits registration requests based on the client's IP address. +It defaults to `per_second: 0.17`, `burst_count: 3`. Uncomment and set to change +the default. -## Captcha ## -# See docs/CAPTCHA_SETUP.md for full details of configuring this. +Example configuration: +``` +rc_registration: + per_second: 0.15 + burst_count: 2 +``` +--- +Config option: `rc_registration_token_validity` -# This homeserver's ReCAPTCHA public key. Must be specified if -# enable_registration_captcha is enabled. -# -#recaptcha_public_key: "YOUR_PUBLIC_KEY" +This option checks the validity of registration tokens that ratelimits requests based on the client's IP address. +Defaults to `per_second: 0.1`, `burst_count: 5`. Uncomment and set to change the default. -# This homeserver's ReCAPTCHA private key. Must be specified if -# enable_registration_captcha is enabled. -# -#recaptcha_private_key: "YOUR_PRIVATE_KEY" +Example configuration: +``` +rc_registration_token_validity: + per_second: 0.3 + burst_count: 6 +``` +--- +Config option: `rc_login` + +This option specifies several limits for login + - one that ratelimits login requests based on the client's IP + address. Defaults to `per_second: 0.17`, `burst_count: 3`. + - one that ratelimits login requests based on the account the + client is attempting to log into. Defaults to `per_second: 0.17`, + `burst_count: 3`. + - one that ratelimits login requests based on the account the + client is attempting to log into, based on the amount of failed login + attempts for this account. Defaults to `per_second: 0.17`, `burst_count: 3`. -# Uncomment to enable ReCaptcha checks when registering, preventing signup -# unless a captcha is answered. Requires a valid ReCaptcha -# public/private key. Defaults to 'false'. -# -#enable_registration_captcha: true +Example configuration: +``` +rc_login: + address: + per_second: 0.15 + burst_count: 5 + account: + per_second: 0.18 + burst_count: 4 + failed_attempts: + per_second: 0.19 + burst_count: 7 +``` +--- +Config option: `rc_admin_redaction` -# The API endpoint to use for verifying m.login.recaptcha responses. -# Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify". -# -#recaptcha_siteverify_api: "https://my.recaptcha.site" +This option sets ratelimiting redactions by room admins. If this is not explicitly +set then it uses the same ratelimiting as per `rc_message`. This is useful +to allow room admins to deal with abuse quickly. Uncomment to explicitly set and change +the default. +Example configuration: +``` +rc_admin_redaction: + per_second: 1 + burst_count: 50 +``` +--- +Config option: `rc_joins` -## TURN ## +This option allows for for ratelimiting number of rooms a user can join. `local` for when +users are joining rooms the server is already in (this is cheap) vs +`remote` for when users are trying to join rooms not on the server (which +can be more expensive). `local` defaults to `per_second: 0.1`, `burst_count: 10`. -# The public URIs of the TURN server to give to clients -# -#turn_uris: [] +Example configuration: +``` +rc_joins: + local: + per_second: 0.2 + burst_count: 15 + remote: + per_second: 0.03 + burst_count: 12 +``` +--- +Config option: `rc_3pid_validation` -# The shared secret used to compute passwords for the TURN server -# -#turn_shared_secret: "YOUR_SHARED_SECRET" +This option ratelimits how often a user or IP can attempt to validate a 3PID. +Defaults to `per_second: 0.003`, `burst_count: 5`. Uncomment and set to change the default. -# The Username and password if the TURN server needs them and -# does not use a token -# -#turn_username: "TURNSERVER_USERNAME" -#turn_password: "TURNSERVER_PASSWORD" +Example configuration: +``` +rc_3pid_validation: + per_second: 0.003 + burst_count: 5 +``` +--- +Config option: `rc_invites` -# How long generated TURN credentials last -# -#turn_user_lifetime: 1h +This option sets ratelimiting how often invites can be sent in a room or to a +specific user. `per_room` defaults to `per_second: 0.3`, `burst_count: 10` and +`per_user` defaults to `per_second: 0.003`, `burst_count: 5`. Uncomment and set to change +the default. -# Whether guests should be allowed to use the TURN server. -# This defaults to True, otherwise VoIP will be unreliable for guests. -# However, it does introduce a slight security risk as it allows users to -# connect to arbitrary endpoints without having first signed up for a -# valid account (e.g. by passing a CAPTCHA). -# -#turn_allow_guests: true +Example configuration: +``` +rc_invites: + per_room: + per_second: 0.5 + burst_count: 5 + per_user: + per_second: 0.004 + burst_count: 3 +``` +--- +Config option: `rc_third_party_invite` +This option ratelimits 3PID invites (i.e. invites sent to a third-party ID +such as an email address or a phone number) based on the account that's +sending the invite. Defaults to `per_second: 0.2`, `burst_count: 10`. Uncomment to set +and change the default. -## Registration ## -# -# Registration can be rate-limited using the parameters in the "Ratelimiting" -# section of this file. +Example configuration: +``` +rc_third_party_invite: + per_second: 0.2 + burst_count: 10 +``` +--- +Config option: `rc_federation` + +The rc_federation configuration is made up of the following settings: + - `window_size`: window size in milliseconds. Defaults to 1000. + - `sleep_limit`: number of federation requests from a single server in + a window before the server will delay processing the request. Defaults to 10. + - `sleep_delay`: duration in milliseconds to delay processing events + from remote servers by if they go over the sleep limit. Defaults to 500. + - `reject_limit`: maximum number of concurrent federation requests + allowed from a single server. Defaults to 50. + - `concurrent`: number of federation requests to concurrently process + from a single server. Defaults to 3. -# Enable registration for new users. -# -#enable_registration: false +Example configuration: +``` +rc_federation: + window_size: 750 + sleep_limit: 15 + sleep_delay: 400 + reject_limit: 40 + concurrent: 5 +``` +--- +Config option: `federation_rr_transactions_per_room_per_second` -# Time that a user's session remains valid for, after they log in. -# -# Note that this is not currently compatible with guest logins. -# -# Note also that this is calculated at login time: changes are not applied -# retrospectively to users who have already logged in. -# -# By default, this is infinite. -# -#session_lifetime: 24h +Target outgoing federation transaction frequency for sending read-receipts, +per-room. -# Time that an access token remains valid for, if the session is -# using refresh tokens. -# For more information about refresh tokens, please see the manual. -# Note that this only applies to clients which advertise support for -# refresh tokens. -# -# Note also that this is calculated at login time and refresh time: -# changes are not applied to existing sessions until they are refreshed. -# -# By default, this is 5 minutes. -# -#refreshable_access_token_lifetime: 5m +If we end up trying to send out more read-receipts, they will get buffered up +into fewer transactions. Defaults to 50. + +Example configuration: +``` +federation_rr_transactions_per_room_per_second: 40 +``` +--- +Config option: `enable_media_store` + +Enable the media store service in the Synapse master. Defaults to true. +Uncomment and set to false if you are using a separate media store worker. + +Example configuration: +``` +enable_media_repo: false +``` +--- +Config option: `media_store_path` + +Directory where uploaded images and attachments are stored. + +Example configuration: +``` +media_store_path: "DATADIR/media_store" +``` +--- +Config option: `media_storage_providers` + +Media storage providers allow media to be stored in different +locations. + +Example configuration: +``` +media_storage_providers: + - module: file_system + + # Whether to store newly uploaded local files + store_local: false + + # Whether to store newly downloaded remote files + store_remote: false + + # Whether to wait for successful storage for local uploads + store_synchronous: false + config: + directory: /mnt/some/other/directory +``` +--- +Config option: `max_upload_size` + +The largest allowed upload size in bytes + +If you are using a reverse proxy you may also need to set this value in +your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default. +See https://matrix-org.github.io/synapse/latest/reverse_proxy.html. + +Example configuration: +``` +max_upload_size: 60M +``` +--- +Config option: `max_image_pixels` + +Maximum number of pixels that will be thumbnailed. Defaults to 32M. + +Example configuration: +``` +max_image_pixels: 35M +``` +--- +Config option: `dynamic_thumbnails` + +Whether to generate new thumbnails on the fly to precisely match +the resolution requested by the client. If true then whenever +a new resolution is requested by the client the server will +generate a new thumbnail. If false the server will pick a thumbnail +from a precalculated list. Defaults to false. + +Example configuration: +``` +dynamic_thumbnails: true +``` +--- +Config option: `thumbnail_sizes` + +List of thumbnails to precalculate when an image is uploaded. The example configuration shows the +default values, uncomment and set to change these defaults. + +Example configuration: +``` +thumbnail_sizes: + - width: 32 + height: 32 + method: crop + - width: 96 + height: 96 + method: crop + - width: 320 + height: 240 + method: scale + - width: 640 + height: 480 + method: scale + - width: 800 + height: 600 + method: scale +``` +Config option: `url_preview_enabled` + +This setting determines whether the preview URL API is enabled. +It is 'false' by default: uncomment and set to 'true' to enable it (and specify a +`url_preview_ip_range_blacklist` blacklist). + +Example configuration: +``` +url_preview_enabled: true +``` +--- +Config option: `url_preview_ip_range_blacklist` + +List of IP address CIDR ranges that the URL preview spider is denied +from accessing. There are no defaults: you must explicitly +specify a list for URL previewing to work. You should specify any +internal services in your network that you do not want synapse to try +to connect to, otherwise anyone in any Matrix room could cause your +synapse to issue arbitrary GET requests to your internal services, +causing serious security issues. + +(0.0.0.0 and :: are always blacklisted, whether or not they are explicitly +listed here, since they correspond to unroutable addresses.) + +This must be specified if `url_preview_enabled` is set. It is recommended that +you uncomment and use the following list as a starting point. + +Note: The value is ignored when an HTTP proxy is in use + +Example configuration: +``` +url_preview_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: `url_preview_ip_range_whitelist` + +This option sets a list of IP address CIDR ranges that the URL preview spider is allowed +to access even if they are specified in url_preview_ip_range_blacklist. +This is useful for specifying exceptions to wide-ranging blacklisted +target IP ranges - e.g. for enabling URL previews for a specific private +website only visible in your network. + +Example configuration: +``` +url_preview_ip_range_whitelist: + - '192.168.1.1' +``` +--- +Config option: `url_preview_url_blacklist` + +Optional list of URL matches that the URL preview spider is +denied from accessing. You should use url_preview_ip_range_blacklist +in preference to this, otherwise someone could define a public DNS +entry that points to a private IP address and circumvent the blacklist. +This is more useful if you know there is an entire shape of URL that +you know that will never want synapse to try to spider. + + +Each list entry is a dictionary of url component attributes as returned +by urlparse.urlsplit as applied to the absolute form of the URL. See +https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit +The values of the dictionary are treated as an filename match pattern +applied to that component of URLs, unless they start with a ^ in which +case they are treated as a regular expression match. If all the +specified component matches for a given list item succeed, the URL is +blacklisted. + +Example configuration: +``` +url_preview_url_blacklist: + # blacklist any URL with a username in its URI + - username: '*' + + # blacklist all *.google.com URLs + - netloc: 'google.com' + - netloc: '*.google.com' + + # blacklist all plain HTTP URLs + - scheme: 'http' + + # blacklist http(s)://www.acme.com/foo + - netloc: 'www.acme.com' + path: '/foo' + + # blacklist any URL with a literal IPv4 address + - netloc: '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' +``` +--- +Config option: `max_spider_size` + +The largest allowed URL preview spidering size in bytes. Defaults to 10M. + +Example configuration: +``` +max_spider_size: 8M +``` +--- +Config option: `url_preview_language` + +A list of values for the Accept-Language HTTP header used when +downloading webpages during URL preview generation. This allows +Synapse to specify the preferred languages that URL previews should +be in when communicating with remote servers. + +Each value is a IETF language tag; a 2-3 letter identifier for a +language, optionally followed by subtags separated by '-', specifying +a country or region variant. + +Multiple values can be provided, and a weight can be added to each by +using quality value syntax (;q=). '*' translates to any language. + +Defaults to "en". + +Example configuration: +``` + url_preview_accept_language: + - en-UK + - en-US;q=0.9 + - fr;q=0.8 + - *;q=0.7 +``` +---- +Config option: `oembed` + +oEmbed allows for easier embedding content from a website. It can be +used for generating URLs previews of services which support it. A default list of oEmbed providers +is included with Synapse. Uncomment `disable_default_providers` and set to `true` to disable using +these default oEmbed URLs. Use `additional_providers` to specify additional files with oEmbed configuration (each +should be in the form of providers.json). By default this list is empty. + +Example configuration: +``` +oembed: + disable_default_providers: true + + additional_providers: + - oembed/my_providers.json +``` +--- +# Captcha + +See docs/CAPTCHA_SETUP.md for full details of configuring captcha. + +--- +Config option: `recaptcha_public_key` + +This homeserver's ReCAPTCHA public key. Must be specified if `enable_registration_captcha` is +enabled. + +Example configuration: +``` +recaptcha_public_key: "YOUR_PUBLIC_KEY" +``` +--- +Config option: `recaptcha_private_key` + +This homeserver's ReCAPTCHA private key. Must be specified if `enable_registration_captcha` is +enabled. + +Example configuration: +``` +recaptcha_private_key: "YOUR_PRIVATE_KEY" +``` +--- +Config option: `enable_registration_captcha` + +Uncomment to enable ReCaptcha checks when registering, preventing signup +unless a captcha is answered. Requires a valid ReCaptcha public/private key. Defaults to 'false'. + +Example configuration: +``` +enable_registration_captcha: true +``` +--- +Config option: `recaptcha_siteverify_api` + +The API endpoint to use for verifying `m.login.recaptcha` responses. +Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify". + +Example configuration: +``` +recaptcha_siteverify_api: "https://my.recaptcha.site" +``` +--- +# TURN + +--- +Config option: `turn_uris` + +The public URIs of the TURN server to give to clients + +Example configuration: +``` +turn_uris: [turn:example.org] +``` +--- +Config option: `turn_shared_secret` + +The shared secret used to compute passwords for the TURN server. + +Example configuration: +``` +turn_shared_secret: "YOUR_SHARED_SECRET" +``` +---- +Config options: `turn_username` and `turn_password` + +The Username and password if the TURN server needs them and does not use a token. + +Example configuration: +``` +turn_username: "TURNSERVER_USERNAME" +turn_password: "TURNSERVER_PASSWORD" +``` +--- +Config option: `turn_user_lifetime` + +How long generated TURN credentials last. Defaults to 1h. + +Example configuration: +``` +turn_user_lifetime: 2h +``` +--- +Config option: `turn_allow_guests` + +Whether guests should be allowed to use the TURN server. This defaults to True, otherwise VoIP will be unreliable for guests. +However, it does introduce a slight security risk as it allows users to connect to arbitrary endpoints without having +first signed up for a valid account (e.g. by passing a CAPTCHA). + +Example usage: +``` +turn_allow_guests: false +``` +--- +# Registration + +Registration can be rate-limited using the parameters in the "Ratelimiting" section of this manual. +[add a link here] +--- +Config option: `enable_registration` + +Enable registration for new users. Defaults to 'false'. + +Example usage: +``` +enable_registration: true +``` +--- +Config option: `session_lifetime` + +Time that a user's session remains valid for, after they log in. + +Note that this is not currently compatible with guest logins. + +Note also that this is calculated at login time: changes are not applied retrospectively to users who have already +logged in. + +By default, this is infinite. + +Example usage: +``` +session_lifetime: 24h +``` +---- +Config option: `refresh_access_token_lifetime` + +Time that an access token remains valid for, if the session is using refresh tokens. + +For more information about refresh tokens, please see the manual. [add link] + +Note that this only applies to clients which advertise support for refresh tokens. + +Note also that this is calculated at login time and refresh time: changes are not applied to +existing sessions until they are refreshed. + +By default, this is 5 minutes. + +Example usage: +``` +refreshable_access_token_lifetime: 10m +``` +--- # Time that a refresh token remains valid for (provided that it is not # exchanged for another one first). From f3fa0cb826bee5d3c7807708dc966fdca75ad580 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Fri, 1 Apr 2022 21:21:28 -0700 Subject: [PATCH 03/11] first formatted draft --- .../configuration/config_documentation.md | 3633 +++++++++-------- 1 file changed, 1962 insertions(+), 1671 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 6b5d6a86cb95..32db000d0424 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -1,9 +1,10 @@ ## Welcome -This is intended as a guide to the synapse configuration-each config option is documented, including instructions -on how to change the default and what sort of behavior to expect if the default is changed. Also included is an example -configuration. If you don't want to spend a lot of time thinking about options, the config as generated sets sensible defaults -for most values. [which values must you fill in? server name, ports?, public base url?] +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 behavior 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. ## Config Conventions @@ -25,15 +26,78 @@ y = year For example, setting `redaction_retention_period: 5m` would remove redacted messages from the database after 5 minutes, rather than 5 months. -## List of config options in the order in which they are found in the real config +## Yaml +The configuration file is a [YAML](https://yaml.org/) 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 a default (if available) will + apply. Thus, in the example below, +``` ---- -Config option: `modules` +``` + +## Index +[Modules](#modules) + +[Server](#server) + +[Homeserver Blocking](#homserver-blocking) + +[TLS](#tls) + +[Federation](#federation) + +[Caching](#caching) + +[Database](#database) + +[Logging](#logging) + +[Ratelimiting](#ratelimiting) + +[Media Store](#media-store) + +[Captcha](#captcha) + +[Turn](#turn) + +[Registration](#registration) + +[Metrics](#metrics) + +[API Configuration](#api-configuration) + +[Signing Keys](#signing-keys) + +[Single Sign On Integration](#single-sign-on-integration) + +[Push](#push) + +[Rooms](#rooms) + +[Opentracing](#opentracing) + +[Workers](#workers) + +[Background Updates](#background-updates) + + + + + +## Modules ## Server admins can expand Synapse's functionality with external modules. + See https://matrix-org.github.io/synapse/latest/modules/index.html for more documentation on how to configure or create custom modules for Synapse. + +--- +Config option: `modules` + +Add modules under this option to extend functionality. Defaults +to none. + Example configuration: ``` modules: @@ -43,6 +107,11 @@ modules: - module: my_other_super_module.SomeClass config: {} ``` +--- +## Server ## + +Define your homeserver name and other base options. + --- Config option: `server_name` @@ -115,8 +184,7 @@ Provided `https:///` on port 443 is routed to Synapse, this option configures Synapse to serve a file at `https:///.well-known/matrix/server`. This will tell other servers to send traffic to port 443 instead. -Uncomment this option in the config to tell other servers to send federation traffic on -port 443, as this option currently defaults to 'false'. +This option currently defaults to 'false'. See https://matrix-org.github.io/synapse/latest/delegate.html for more information. @@ -161,7 +229,7 @@ require_auth_for_profile_requests: true --- Config option: `limit_profile_requests_to_users_who_share_rooms` -Uncomment to require a user to share a room with another user in order +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'. @@ -173,7 +241,7 @@ limit_profile_requests_to_users_who_share_rooms: true --- Config option: `include_profile_data_on_invite` -Uncomment to prevent a user's profile data from being retrieved and +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. @@ -207,17 +275,19 @@ allow_public_rooms_over_federation: true --- Config option: `default_room_version` -The default room version for newly created rooms. +The default room version for newly created rooms on this server. Known room versions are listed here: https://spec.matrix.org/latest/rooms/#complete-list-of-room-versions For example, for room version 1, `default_room_version` should be set -to "1". +to "1". + +Currently defualts to "9". Example configuration: ``` -default_room_version: "6" +default_room_version: "9" ``` --- Config option: `gc_thresholds` @@ -247,7 +317,6 @@ Config option: `filter_timeline_limit` Set the limit on the returned events in the timeline in the get and sync operations. Defaults to 100. -1 means no upper limit. -Uncomment to increase the limit to 5000 or set your own value. Example configuration: ``` @@ -338,20 +407,20 @@ configuration. Options for each listener include: -    `port`: the TCP port to bind to +`port`: the TCP port to bind to -    `bind_addresses`: a list of local addresses to listen on. The default is +`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: +`type`: the type of listener. Normally `http`, but other valid options are: -        `manhole`: (see https://matrix-org.github.io/synapse/latest/manhole.html), +* `manhole`: (see https://matrix-org.github.io/synapse/latest/manhole.html), -        `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), +* `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), -        `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). +* `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). -        `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. +* `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. @@ -359,11 +428,11 @@ behind a reverse-proxy. `resources`: Only valid for an 'http' listener. A list of resources to host on this port. Options for each resource are: -`names`: a list of names of HTTP resources. See below for a list of valid resource names. +* `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. +* `compress`: set to true to enable HTTP compression for this resource. -    `additional_resources`: Only valid for an 'http' listener. A map of +`additional_resources`: Only valid for an 'http' listener. A map of additional endpoints which should be loaded via dynamic modules. Valid resource names are: @@ -374,13 +443,13 @@ Valid resource names are: `federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid` -    `keys`: the key discovery API (/_matrix/keys). +`keys`: the key discovery API (/_matrix/keys). -    `media`: the media API (/_matrix/media). +`media`: the media API (/_matrix/media). -    `metrics`: the metrics interface. See https://matrix-org.github.io/synapse/latest/metrics-howto.html. +`metrics`: the metrics interface. See https://matrix-org.github.io/synapse/latest/metrics-howto.html. -    `openid`: OpenID authentication. +`openid`: OpenID authentication. `replication`: the HTTP replication API (/_synapse/replication). See https://matrix-org.github.io/synapse/latest/workers.html. @@ -431,22 +500,21 @@ Example configuration #2: type: manhole ``` --- -Config optoin: `manhole_settings` +Config option: `manhole_settings` -Connection settings for the manhole. Link to manhole docs. +Connection settings for the manhole. You can find more information +on the manhole [here](../../manhole.md). Manhole settings 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: - # The username for the manhole. This defaults to 'matrix'. username: manhole - - # The password for the manhole. This defaults to 'rabbithole'. password: mypassword - - # 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. ssh_priv_key_path: CONFDIR/id_rsa ssh_pub_key_path: CONFDIR/id_rsa.pub ``` @@ -457,7 +525,7 @@ 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 +`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. @@ -468,6 +536,11 @@ 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`. @@ -477,13 +550,14 @@ Example configuration: admin_contact: 'mailto:admin@server.com' ``` --- -Config option: `hs_disabled` +Config option: `hs_disabled` and `hs_disabled_message` -Config option: `hs_disabled_message` +Blocks users from connecting to homeserver and provides a human-readable reason +why the connection was blocked. Defaults to false. Example configuration: ``` -hs_disabled: false +hs_disabled: true hs_disabled_message: 'Human readable reason for why the HS is blocked' ``` --- @@ -492,15 +566,17 @@ 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: false +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. +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. Example configuration: ``` @@ -548,7 +624,8 @@ 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. Uncomment and add users to enable. +Defaults to none. Add accounts by specifying the `medium` and `address` of the +reserved threepid (3rd party identifier). Example configuration: ``` @@ -560,7 +637,7 @@ mau_limit_reserved_threepids: Config option: `server_context` This option is used by phonehome stats to group together related servers. -Defaults to none. Uncomment and add a context to enable. +Defaults to none. Example configuration: ``` @@ -572,31 +649,29 @@ 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. Uncomment to set the options as illustrated below. +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. +users in the room. Example configuration: ``` limit_remote_rooms: - # Enables room complexity checking. enabled: true - - # the limit above which rooms cannot be joined. The default is 1.0. complexity: 0.5 - - # override the error which is returned when the room is too complex. - complexity_error: "This room is too complex." - - # allow server admins to join complex rooms. Default is false. + 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'. +Defaults to true. Example configuration: ``` @@ -630,7 +705,6 @@ Config option: `allowed_avatar_mimetypes` The MIME types allowed for user avatars. Defaults to no restriction. - Note that user avatar changes will not work if this is set without using Synapse's media repository. @@ -644,7 +718,7 @@ Config option: `redaction_retention_period` How long to keep redacted events in unredacted form in the database. After this period redacted events get replaced with their redacted form in the DB. -Defaults to `7d`. Uncomment and set to `null` to disable. +Defaults to `7d`. Set to `null` to disable. Example configuration: ``` @@ -655,7 +729,7 @@ Config option: `user_ips_max_age` How long to track users' last seen time and IPs in the database. -Defaults to `28d`. Uncomment and set to `null` to disable clearing out of old rows. +Defaults to `28d`. Set to `null` to disable clearing out of old rows. Example configuration: ``` @@ -664,7 +738,7 @@ user_ips_max_age: 14d --- Config option: `request_token_inhibit_3pid_errors` -Inhibits the /requestToken endpoints from returning an error that might leak +Inhibits the `/requestToken` endpoints from returning an error that might leak information about whether an e-mail address is in use or not on this homeserver. Defaults to false. Note that for some endpoints the error situation is the e-mail already being @@ -679,7 +753,7 @@ request_token_inhibit_3pid_errors: true --- Config option: `next_link_domain_whitelist` -A list of domains that the domain portion of 'next_link' parameters +A list of domains that the domain portion of `next_link` parameters must match. This parameter is optionally provided by clients while requesting @@ -701,8 +775,9 @@ next_link_domain_whitelist: ["matrix.org"] --- Config option: `templates` and `custom_template_directory` -Templates to use when generating email or HTML page contents. The `custom_template_directory` -determines which directory Synapse will try to find template files in to use to generate email or HTML page contents. +These options define templates to use when generating email or HTML page contents. +The `custom_template_directory` determines which directory Synapse will try to +find template files in to use to generate email or HTML page contents. If not set, or a file is not found within the template directory, a default template from within the Synapse package will be used. @@ -731,63 +806,68 @@ purged are ignored and not stored again. The message retention policies feature is disabled by default. +Associated options are: +* `default_policy`: Default retention policy. If set, Synapse will apply it to rooms that lack the + 'm.room.retention' state event. This option is further specified by the + `min_lifetime` and `max_lifetime` options associated with it. Note that the + value of `min_lifetime` doesn't matter much because Synapse doesn't take it into account yet. + +* `allowed_lifetime_min` and `allowed_lifetime_max`: Retention policy limits. If + set, and the state of a room contains a `m.room.retention` event in its state + which contains a `min_lifetime` or a `max_lifetime` that's out of these bounds, + Synapse will cap the room's policy to these limits when running purge jobs. + +* `purge_jobs` and the associated `shortest_max_lifetime` and `longest_max_lifetime`: + Server admins can define the settings of the background jobs purging the + events whose lifetime has expired under the `purge_jobs` section. + + If no configuration is provided for this option, a single job will be set up to delete + expired events in every room daily. + + Each job's configuration defines which range of message lifetimes the job + takes care of. For example, if `shortest_max_lifetime` is '2d' and + `longest_max_lifetime` is '3d', the job will handle purging expired events in + rooms whose state defines a `max_lifetime` that's both higher than 2 days, and + lower than or equal to 3 days. Both the minimum and the maximum value of a + range are optional, e.g. a job with no `shortest_max_lifetime` and a + `longest_max_lifetime` of '3d' will handle every room with a retention policy + whose `max_lifetime` is lower than or equal to three days. + + The rationale for this per-job configuration is that some rooms might have a + retention policy with a low `max_lifetime`, where history needs to be purged + of outdated messages on a more frequent basis than for the rest of the rooms + (e.g. every 12h), but not want that purge to be performed by a job that's + iterating over every room it knows, which could be heavy on the server. + + If any purge job is configured, it is strongly recommended to have at least + a single job with neither `shortest_max_lifetime` nor `longest_max_lifetime` + set, or one job without `shortest_max_lifetime` and one job without + `longest_max_lifetime` set. Otherwise some rooms might be ignored, even if + `allowed_lifetime_min` and `allowed_lifetime_max` are set, because capping a + room's policy to these values is done after the policies are retrieved from + Synapse's database (which is done using the range specified in a purge job's + configuration). + Example configuration: ``` retention: enabled: true - - # Default retention policy. If set, Synapse will apply it to rooms that lack the - # 'm.room.retention' state event. Currently, the value of 'min_lifetime' doesn't - # matter much because Synapse doesn't take it into account yet. - # default_policy: min_lifetime: 1d max_lifetime: 1y - - # Retention policy limits. If set, and the state of a room contains a - # 'm.room.retention' event in its state which contains a 'min_lifetime' or a - # 'max_lifetime' that's out of these bounds, Synapse will cap the room's policy - # to these limits when running purge jobs. - allowed_lifetime_min: 1d allowed_lifetime_max: 1y - - # Server admins can define the settings of the background jobs purging the - # events which lifetime has expired under the 'purge_jobs' section. - # - # If no configuration is provided, a single job will be set up to delete expired - # events in every room daily. - # - # Each job's configuration defines which range of message lifetimes the job - # takes care of. For example, if 'shortest_max_lifetime' is '2d' and - # 'longest_max_lifetime' is '3d', the job will handle purging expired events in - # rooms whose state defines a 'max_lifetime' that's both higher than 2 days, and - # lower than or equal to 3 days. Both the minimum and the maximum value of a - # range are optional, e.g. a job with no 'shortest_max_lifetime' and a - # 'longest_max_lifetime' of '3d' will handle every room with a retention policy - # which 'max_lifetime' is lower than or equal to three days. - # - # The rationale for this per-job configuration is that some rooms might have a - # retention policy with a low 'max_lifetime', where history needs to be purged - # of outdated messages on a more frequent basis than for the rest of the rooms - # (e.g. every 12h), but not want that purge to be performed by a job that's - # iterating over every room it knows, which could be heavy on the server. - # - # If any purge job is configured, it is strongly recommended to have at least - # a single job with neither 'shortest_max_lifetime' nor 'longest_max_lifetime' - # set, or one job without 'shortest_max_lifetime' and one job without - # 'longest_max_lifetime' set. Otherwise some rooms might be ignored, even if - # 'allowed_lifetime_min' and 'allowed_lifetime_max' are set, because capping a - # room's policy to these values is done after the policies are retrieved from - # Synapse's database (which is done using the range specified in a purge job's - # configuration). - purge_jobs: - longest_max_lifetime: 3d interval: 12h - shortest_max_lifetime: 3d - interval: 1d + interval: 1d ``` +--- +## TLS ## + +Options relating to TLS + --- Config option: `tls_certificate_path` @@ -816,7 +896,7 @@ tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" Config option: `federation_verify_certificates` Whether to verify TLS server certificates for outbound federation requests. -Defaults to `true`. To disable certificate verification, uncomment the option. +Defaults to true. To disable certificate verification, set the option to false. Example configuration: ``` @@ -873,6 +953,11 @@ federation_custom_ca_list: - myCA2.pem - myCA3.pem ``` +--- +## Federation ## + +Options related to federation. + --- Config option: `federation_domain_whitelist` @@ -908,9 +993,9 @@ federation_metrics_domains: --- Config option: `allow_profile_lookup_over_federation` -Uncomment to disable profile lookup over federation. By default, the +Set to false to disable profile lookup over federation. By default, the Federation API allows other homeservers to obtain profile data of any user -on this homeserver. Defaults to 'true'. +on this homeserver. Example configuration: ``` @@ -919,99 +1004,117 @@ allow_profile_lookup_over_federation: false --- Config option: `allow_device_name_lookup_over_federation` -Uncomment this option to disable device display name lookup over federation. By default, the +Set this option to false to disable device display name lookup over federation. By default, the Federation API allows other homeservers to obtain device display names of any user -on this homeserver. Defaults to 'true'. +on this homeserver. Example configuration: ``` allow_device_name_lookup_over_federation: false ``` +--- +## Caching ## + +Options related to caching + --- Config option: `event_cache_size` The number of events to cache in memory. Not affected by -`caches.global_factor`. +`caches.global_factor`. Defaults to 10K Example configuration: ``` -event_cache_size: 10K +event_cache_size: 15K ``` --- Config option: `cache` and associated values -Caching can be configured through the following options. - A cache 'factor' is a multiplier that can be applied to each of Synapse's caches in order to increase or decrease the maximum number of entries that can be stored. +Caching can be configured through the following options: + +* `global_factor`: Controls the global cache factor, which is the default cache factor + for all caches if a specific factor for that cache is not otherwise + set. + + This can also be set by the `SYNAPSE_CACHE_FACTOR` environment + variable. Setting by environment variable takes priority over + setting through the config file. + + Defaults to 0.5, which will halve the size of all caches. + +* `per_cache_factors`: A dictionary of cache name to cache factor for that individual + cache. Overrides the global cache factor for a given cache. + + These can also be set through environment variables comprised + of `SYNAPSE_CACHE_FACTOR_` + the name of the cache in capital + letters and underscores. Setting by environment variable + takes priority over setting through the config file. + Ex. `SYNAPSE_CACHE_FACTOR_GET_USERS_WHO_SHARE_ROOM_WITH_USER=2.0` + + Some caches have '*' and other characters that are not + alphanumeric or underscores. These caches can be named with or + without the special characters stripped. For example, to specify + the cache factor for `*stateGroupCache*` via an environment + variable would be `SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0`. + +* `expire_caches`: Controls whether cache entries are evicted after a specified time + period. Defaults to true. Set to false to disable this feature. Note that never expiring + caches may result in excessive memory usage. + +* `cache_entry_ttl`: If `expire_caches` is enabled, this flag controls how long an entry can + be in a cache without having been accessed before being evicted. + Defaults to 30m. + +* `sync_response_cache_duration`: Controls how long the results of a /sync request are + cached for after a successful response is returned. A higher duration can help clients + with intermittent connections, at the cost of higher memory usage. + By default, this is zero, which means that sync responses are not cached + at all. + + Example configuration: ``` caches: - # Controls the global cache factor, which is the default cache factor - # for all caches if a specific factor for that cache is not otherwise - # set. - # - # This can also be set by the "SYNAPSE_CACHE_FACTOR" environment - # variable. Setting by environment variable takes priority over - # setting through the config file. - # - # Defaults to 0.5, which will half the size of all caches. - # global_factor: 1.0 - - # A dictionary of cache name to cache factor for that individual - # cache. Overrides the global cache factor for a given cache. - # - # These can also be set through environment variables comprised - # of "SYNAPSE_CACHE_FACTOR_" + the name of the cache in capital - # letters and underscores. Setting by environment variable - # takes priority over setting through the config file. - # Ex. SYNAPSE_CACHE_FACTOR_GET_USERS_WHO_SHARE_ROOM_WITH_USER=2.0 - # - # Some caches have '*' and other characters that are not - # alphanumeric or underscores. These caches can be named with or - # without the special characters stripped. For example, to specify - # the cache factor for `*stateGroupCache*` via an environment - # variable would be `SYNAPSE_CACHE_FACTOR_STATEGROUPCACHE=2.0`. - # per_cache_factors: get_users_who_share_room_with_user: 2.0 - - # Controls how long an entry can be in a cache without having been - # accessed before being evicted. Defaults to None, which means - # entries are never evicted based on time. - # - expiry_time: 30m - - # Controls how long the results of a /sync request are cached for after - # a successful response is returned. A higher duration can help clients with - # intermittent connections, at the cost of higher memory usage. - # - # By default, this is zero, which means that sync responses are not cached - # at all. - # + expire_caches: false sync_response_cache_duration: 2m ``` +--- +## Database ## +Config options related to database settings. + --- Config option: `database` -The 'database' setting defines the database that synapse uses to store all of +The `database` setting defines the database that synapse uses to store all of its data. -'name' gives the database engine to use: either 'sqlite3' (for SQLite) or -'psycopg2' (for PostgreSQL). +Associated options: + +* `name`: this option specifies the database engine to use: either `sqlite3` (for SQLite) + or `psycopg2` (for PostgreSQL). If no name is specified Synapse will default to SQLite. -'txn_limit' gives the maximum number of transactions to run per connection -before reconnecting. Defaults to 0, which means no limit. +* `txn_limit` gives the maximum number of transactions to run per connection + before reconnecting. Defaults to 0, which means no limit. -'args' gives options which are passed through to the database engine, -except for options starting 'cp_', which are used to configure the Twisted -connection pool. For a reference to valid arguments, see: -* for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect -* for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS -* for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ +* `allow_unsafe_locale` is an option specific to Postgres. Under the default behavior, Synapse will refuse to + start if the postgres db is set to a non-C locale. You can override this behavior (which is *not* recommended) + by setting `allow_unsafe_locale` to true. Note that doing so may corrupt your database. You can find more information + here: https://matrix-org.github.io/synapse/latest/postgres.html#fixing-incorrect-collate-or-ctype and here: + https://wiki.postgresql.org/wiki/Locale_data_changes + +* `args` gives options which are passed through to the database engine, + except for options starting with `cp_`, which are used to configure the Twisted + connection pool. For a reference to valid arguments, see: + * for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect + * for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS + * for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ For more information on using Synapse with Postgres, see https://matrix-org.github.io/synapse/latest/postgres.html. @@ -1038,10 +1141,14 @@ database: cp_min: 5 cp_max: 10 ``` +--- +## Logging ## +Config options related to logging. + --- Config option: `log_config` -A yaml python logging config file as described by +This option specifies a yaml python logging config file as described by https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema Example configuration: @@ -1049,10 +1156,12 @@ Example configuration: log_config: "CONFDIR/SERVERNAME.log.config" ``` --- -# Ratelimiting +## Ratelimiting ## +Options related to ratelimiting in Synapse. + Each ratelimiting configuration is made of two parameters: - - per_second: number of requests a client can send per second. - - burst_count: number of requests a client can send before being throttled. + - `per_second`: number of requests a client can send per second. + - `burst_count`: number of requests a client can send before being throttled. --- Config option: `rc_message` @@ -1060,8 +1169,7 @@ Config option: `rc_message` Ratelimiting settings for client messaging. This is a ratelimiting option for messages that ratelimits sending based on the account the client -is using. It defaults to: `per_second: 0.2`, `burst_count: 10`. Uncomment and set -to change the default. +is using. It defaults to: `per_second: 0.2`, `burst_count: 10`. Example configuration: ``` @@ -1073,8 +1181,7 @@ rc_message: Config option: `rc_registration` This option ratelimits registration requests based on the client's IP address. -It defaults to `per_second: 0.17`, `burst_count: 3`. Uncomment and set to change -the default. +It defaults to `per_second: 0.17`, `burst_count: 3`. Example configuration: ``` @@ -1085,8 +1192,9 @@ rc_registration: --- Config option: `rc_registration_token_validity` -This option checks the validity of registration tokens that ratelimits requests based on the client's IP address. -Defaults to `per_second: 0.1`, `burst_count: 5`. Uncomment and set to change the default. +This option checks the validity of registration tokens that ratelimits requests based on +the client's IP address. +Defaults to `per_second: 0.1`, `burst_count: 5`. Example configuration: ``` @@ -1097,15 +1205,17 @@ rc_registration_token_validity: --- Config option: `rc_login` -This option specifies several limits for login - - one that ratelimits login requests based on the client's IP - address. Defaults to `per_second: 0.17`, `burst_count: 3`. - - one that ratelimits login requests based on the account the - client is attempting to log into. Defaults to `per_second: 0.17`, - `burst_count: 3`. - - one that ratelimits login requests based on the account the - client is attempting to log into, based on the amount of failed login - attempts for this account. Defaults to `per_second: 0.17`, `burst_count: 3`. +This option specifies several limits for login: +* `address` ratelimits login requests based on the client's IP + address. Defaults to `per_second: 0.17`, `burst_count: 3`. + +* `account` ratelimits login requests based on the account the + client is attempting to log into. Defaults to `per_second: 0.17`, + `burst_count: 3`. + +* `failted_attempts` ratelimits login requests based on the account the + client is attempting to log into, based on the amount of failed login + attempts for this account. Defaults to `per_second: 0.17`, `burst_count: 3`. Example configuration: ``` @@ -1125,8 +1235,7 @@ Config option: `rc_admin_redaction` This option sets ratelimiting redactions by room admins. If this is not explicitly set then it uses the same ratelimiting as per `rc_message`. This is useful -to allow room admins to deal with abuse quickly. Uncomment to explicitly set and change -the default. +to allow room admins to deal with abuse quickly. Example configuration: ``` @@ -1137,10 +1246,15 @@ rc_admin_redaction: --- Config option: `rc_joins` -This option allows for for ratelimiting number of rooms a user can join. `local` for when -users are joining rooms the server is already in (this is cheap) vs -`remote` for when users are trying to join rooms not on the server (which -can be more expensive). `local` defaults to `per_second: 0.1`, `burst_count: 10`. +This option allows for ratelimiting number of rooms a user can join. It's options +are + +* `local`: ratelimits when users are joining rooms the server is already in. + Defaults to `per_second: 0.1`, `burst_count: 10`. + +* `remote`: ratelimits when users are trying to join rooms not on the server (which + can be more computationally expensive than restricting locally). Defaults to + `per_second: 0.01`, `burst_count: 10` Example configuration: ``` @@ -1156,7 +1270,7 @@ rc_joins: Config option: `rc_3pid_validation` This option ratelimits how often a user or IP can attempt to validate a 3PID. -Defaults to `per_second: 0.003`, `burst_count: 5`. Uncomment and set to change the default. +Defaults to `per_second: 0.003`, `burst_count: 5`. Example configuration: ``` @@ -1169,8 +1283,7 @@ Config option: `rc_invites` This option sets ratelimiting how often invites can be sent in a room or to a specific user. `per_room` defaults to `per_second: 0.3`, `burst_count: 10` and -`per_user` defaults to `per_second: 0.003`, `burst_count: 5`. Uncomment and set to change -the default. +`per_user` defaults to `per_second: 0.003`, `burst_count: 5`. Example configuration: ``` @@ -1187,8 +1300,7 @@ Config option: `rc_third_party_invite` This option ratelimits 3PID invites (i.e. invites sent to a third-party ID such as an email address or a phone number) based on the account that's -sending the invite. Defaults to `per_second: 0.2`, `burst_count: 10`. Uncomment to set -and change the default. +sending the invite. Defaults to `per_second: 0.2`, `burst_count: 10`. Example configuration: ``` @@ -1200,15 +1312,15 @@ rc_third_party_invite: Config option: `rc_federation` The rc_federation configuration is made up of the following settings: - - `window_size`: window size in milliseconds. Defaults to 1000. - - `sleep_limit`: number of federation requests from a single server in - a window before the server will delay processing the request. Defaults to 10. - - `sleep_delay`: duration in milliseconds to delay processing events - from remote servers by if they go over the sleep limit. Defaults to 500. - - `reject_limit`: maximum number of concurrent federation requests - allowed from a single server. Defaults to 50. - - `concurrent`: number of federation requests to concurrently process - from a single server. Defaults to 3. +* `window_size`: window size in milliseconds. Defaults to 1000. +* `sleep_limit`: number of federation requests from a single server in + a window before the server will delay processing the request. Defaults to 10. +* `sleep_delay`: duration in milliseconds to delay processing events + from remote servers by if they go over the sleep limit. Defaults to 500. +* `reject_limit`: maximum number of concurrent federation requests + allowed from a single server. Defaults to 50. +* `concurrent`: number of federation requests to concurrently process + from a single server. Defaults to 3. Example configuration: ``` @@ -1222,7 +1334,7 @@ rc_federation: --- Config option: `federation_rr_transactions_per_room_per_second` -Target outgoing federation transaction frequency for sending read-receipts, +Sets outgoing federation transaction frequency for sending read-receipts, per-room. If we end up trying to send out more read-receipts, they will get buffered up @@ -1233,10 +1345,14 @@ Example configuration: federation_rr_transactions_per_room_per_second: 40 ``` --- -Config option: `enable_media_store` +## Media Store ## +Config options relating to Synapse media store. + +--- +Config option: `enable_media_repo` Enable the media store service in the Synapse master. Defaults to true. -Uncomment and set to false if you are using a separate media store worker. +Set to false if you are using a separate media store worker. Example configuration: ``` @@ -1255,20 +1371,19 @@ media_store_path: "DATADIR/media_store" Config option: `media_storage_providers` Media storage providers allow media to be stored in different -locations. +locations. Defaults to none. Associated options are: +* `module`: type of resource, e.g. `file_system`, and associated options: + * `store_local`: whether to store newly uploaded local files + * `store_remote`: whether to store newly downloaded local files + * `store_synchronous`: whether to wait for successful storage for local uploads + * `config`: sets a path to the resource through the `directory` option Example configuration: ``` media_storage_providers: - module: file_system - - # Whether to store newly uploaded local files store_local: false - - # Whether to store newly downloaded remote files store_remote: false - - # Whether to wait for successful storage for local uploads store_synchronous: false config: directory: /mnt/some/other/directory @@ -1311,8 +1426,10 @@ dynamic_thumbnails: true --- Config option: `thumbnail_sizes` -List of thumbnails to precalculate when an image is uploaded. The example configuration shows the -default values, uncomment and set to change these defaults. +List of thumbnails to precalculate when an image is uploaded. Associated settings are: +* `width` +* `height` +* `method`: i.e. `crop`, `scale`, etc. Example configuration: ``` @@ -1336,8 +1453,8 @@ thumbnail_sizes: Config option: `url_preview_enabled` This setting determines whether the preview URL API is enabled. -It is 'false' by default: uncomment and set to 'true' to enable it (and specify a -`url_preview_ip_range_blacklist` blacklist). +It is disabled by default. Set to true to enable. If enabled you must specify a +`url_preview_ip_range_blacklist` blacklist. Example configuration: ``` @@ -1358,9 +1475,9 @@ causing serious security issues. listed here, since they correspond to unroutable addresses.) This must be specified if `url_preview_enabled` is set. It is recommended that -you uncomment and use the following list as a starting point. +you use the following example list as a starting point. -Note: The value is ignored when an HTTP proxy is in use +Note: The value is ignored when an HTTP proxy is in use. Example configuration: ``` @@ -1389,7 +1506,7 @@ url_preview_ip_range_blacklist: Config option: `url_preview_ip_range_whitelist` This option sets a list of IP address CIDR ranges that the URL preview spider is allowed -to access even if they are specified in url_preview_ip_range_blacklist. +to access even if they are specified in `url_preview_ip_range_blacklist`. This is useful for specifying exceptions to wide-ranging blacklisted target IP ranges - e.g. for enabling URL previews for a specific private website only visible in your network. @@ -1403,17 +1520,23 @@ url_preview_ip_range_whitelist: Config option: `url_preview_url_blacklist` Optional list of URL matches that the URL preview spider is -denied from accessing. You should use url_preview_ip_range_blacklist +denied from accessing. You should use `url_preview_ip_range_blacklist` in preference to this, otherwise someone could define a public DNS entry that points to a private IP address and circumvent the blacklist. This is more useful if you know there is an entire shape of URL that you know that will never want synapse to try to spider. - Each list entry is a dictionary of url component attributes as returned by urlparse.urlsplit as applied to the absolute form of the URL. See -https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit -The values of the dictionary are treated as an filename match pattern +https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit for more +information. Some examples are: + +* `username` +* `netloc` +* `scheme` +* `path` + +The values of the dictionary are treated as a filename match pattern applied to that component of URLs, unless they start with a ^ in which case they are treated as a regular expression match. If all the specified component matches for a given list item succeed, the URL is @@ -1478,7 +1601,7 @@ Config option: `oembed` oEmbed allows for easier embedding content from a website. It can be used for generating URLs previews of services which support it. A default list of oEmbed providers -is included with Synapse. Uncomment `disable_default_providers` and set to `true` to disable using +is included with Synapse. Set `disable_default_providers` to true to disable using these default oEmbed URLs. Use `additional_providers` to specify additional files with oEmbed configuration (each should be in the form of providers.json). By default this list is empty. @@ -1486,12 +1609,11 @@ Example configuration: ``` oembed: disable_default_providers: true - additional_providers: - oembed/my_providers.json ``` --- -# Captcha +## Captcha ## See docs/CAPTCHA_SETUP.md for full details of configuring captcha. @@ -1519,7 +1641,8 @@ recaptcha_private_key: "YOUR_PRIVATE_KEY" Config option: `enable_registration_captcha` Uncomment to enable ReCaptcha checks when registering, preventing signup -unless a captcha is answered. Requires a valid ReCaptcha public/private key. Defaults to 'false'. +unless a captcha is answered. Requires a valid ReCaptcha public/private key. +Defaults to false. Example configuration: ``` @@ -1529,14 +1652,15 @@ enable_registration_captcha: true Config option: `recaptcha_siteverify_api` The API endpoint to use for verifying `m.login.recaptcha` responses. -Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify". +Defaults to `https://www.recaptcha.net/recaptcha/api/siteverify`. Example configuration: ``` recaptcha_siteverify_api: "https://my.recaptcha.site" ``` --- -# TURN +## TURN ## +Options related to adding a TURN server to Synapse. --- Config option: `turn_uris` @@ -1578,29 +1702,41 @@ turn_user_lifetime: 2h --- Config option: `turn_allow_guests` -Whether guests should be allowed to use the TURN server. This defaults to True, otherwise VoIP will be unreliable for guests. -However, it does introduce a slight security risk as it allows users to connect to arbitrary endpoints without having -first signed up for a valid account (e.g. by passing a CAPTCHA). +Whether guests should be allowed to use the TURN server. This defaults to true, otherwise +VoIP will be unreliable for guests. However, it does introduce a slight security risk as +it allows users to connect to arbitrary endpoints without having first signed up for a valid account (e.g. by passing a CAPTCHA). Example usage: ``` turn_allow_guests: false ``` --- -# Registration +## Registration ## + +Registration can be rate-limited using the parameters in the [Ratelimiting](#ratelimiting) section of this manual. -Registration can be rate-limited using the parameters in the "Ratelimiting" section of this manual. -[add a link here] --- Config option: `enable_registration` -Enable registration for new users. Defaults to 'false'. +Enable registration for new users. Defaults to false. It is highly recommended that if you enable registration, +you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration +without any verification, you must also set `enable_registration_without_verification` to true. Example usage: ``` enable_registration: true ``` --- +Config option: `enable_registration_without_verification` +Enable registration without email or captcha verification. Note: this option is *not* recommended, +as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect +unless `enable_registration` is also enabled. + +Example usage: +``` +enable_registration_without_verification: true +``` +--- Config option: `session_lifetime` Time that a user's session remains valid for, after they log in. @@ -1621,7 +1757,7 @@ Config option: `refresh_access_token_lifetime` Time that an access token remains valid for, if the session is using refresh tokens. -For more information about refresh tokens, please see the manual. [add link] +For more information about refresh tokens, please see the [manual](user_authentication/refresh_tokens.md). Note that this only applies to clients which advertise support for refresh tokens. @@ -1635,1494 +1771,1649 @@ Example usage: refreshable_access_token_lifetime: 10m ``` --- +Config option: `refresh_token_lifetime: 24h` -# Time that a refresh token remains valid for (provided that it is not -# exchanged for another one first). -# This option can be used to automatically log-out inactive sessions. -# Please see the manual for more information. -# -# Note also that this is calculated at login time and refresh time: -# changes are not applied to existing sessions until they are refreshed. -# -# By default, this is infinite. -# -#refresh_token_lifetime: 24h - -# Time that an access token remains valid for, if the session is NOT -# using refresh tokens. -# Please note that not all clients support refresh tokens, so setting -# this to a short value may be inconvenient for some users who will -# then be logged out frequently. -# -# Note also that this is calculated at login time: changes are not applied -# retrospectively to existing sessions for users that have already logged in. -# -# By default, this is infinite. -# -#nonrefreshable_access_token_lifetime: 24h - -# The user must provide all of the below types of 3PID when registering. -# -#registrations_require_3pid: -# - email -# - msisdn - -# Explicitly disable asking for MSISDNs from the registration -# flow (overrides registrations_require_3pid if MSISDNs are set as required) -# -#disable_msisdn_registration: true - -# Mandate that users are only allowed to associate certain formats of -# 3PIDs with accounts on this server. -# -#allowed_local_3pids: -# - medium: email -# pattern: '^[^@]+@matrix\.org$' -# - medium: email -# pattern: '^[^@]+@vector\.im$' -# - medium: msisdn -# pattern: '\+44' - -# Enable 3PIDs lookup requests to identity servers from this server. -# -#enable_3pid_lookup: true - -# Require users to submit a token during registration. -# Tokens can be managed using the admin API: -# https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html -# Note that `enable_registration` must be set to `true`. -# Disabling this option will not delete any tokens previously generated. -# Defaults to false. Uncomment the following to require tokens: -# -#registration_requires_token: true - -# If set, allows registration of standard or admin accounts by anyone who -# has the shared secret, even if registration is otherwise disabled. -# -#registration_shared_secret: - -# Set the number of bcrypt rounds used to generate password hash. -# Larger numbers increase the work factor needed to generate the hash. -# The default number is 12 (which equates to 2^12 rounds). -# N.B. that increasing this will exponentially increase the time required -# to register or login - e.g. 24 => 2^24 rounds which will take >20 mins. -# -#bcrypt_rounds: 12 - -# Allows users to register as guests without a password/email/etc, and -# participate in rooms hosted on this server which have been made -# accessible to anonymous users. -# -#allow_guest_access: false - -# The identity server which we suggest that clients should use when users log -# in on this server. -# -# (By default, no suggestion is made, so it is left up to the client. -# This setting is ignored unless public_baseurl is also explicitly set.) -# -#default_identity_server: https://matrix.org - -# Handle threepid (email/phone etc) registration and password resets through a set of -# *trusted* identity servers. Note that this allows the configured identity server to -# reset passwords for accounts! -# -# Be aware that if `email` is not set, and SMTP options have not been -# configured in the email config block, registration and user password resets via -# email will be globally disabled. -# -# Additionally, if `msisdn` is not set, registration and password resets via msisdn -# will be disabled regardless, and users will not be able to associate an msisdn -# identifier to their account. This is due to Synapse currently not supporting -# any method of sending SMS messages on its own. -# -# To enable using an identity server for operations regarding a particular third-party -# identifier type, set the value to the URL of that identity server as shown in the -# examples below. -# -# Servers handling the these requests must answer the `/requestToken` endpoints defined -# by the Matrix Identity Service API specification: -# https://matrix.org/docs/spec/identity_service/latest -# -account_threepid_delegates: - #email: https://example.com # Delegate email sending to example.com - #msisdn: http://localhost:8090 # Delegate SMS sending to this local process - -# Whether users are allowed to change their displayname after it has -# been initially set. Useful when provisioning users based on the -# contents of a third-party directory. -# -# Does not apply to server administrators. Defaults to 'true' -# -#enable_set_displayname: false - -# Whether users are allowed to change their avatar after it has been -# initially set. Useful when provisioning users based on the contents -# of a third-party directory. -# -# Does not apply to server administrators. Defaults to 'true' -# -#enable_set_avatar_url: false - -# Whether users can change the 3PIDs associated with their accounts -# (email address and msisdn). -# -# Defaults to 'true' -# -#enable_3pid_changes: false - -# Users who register on this homeserver will automatically be joined -# to these rooms. -# -# By default, any room aliases included in this list will be created -# as a publicly joinable room when the first user registers for the -# homeserver. This behaviour can be customised with the settings below. -# If the room already exists, make certain it is a publicly joinable -# room. The join rule of the room must be set to 'public'. -# -#auto_join_rooms: -# - "#example:example.com" - -# Where auto_join_rooms are specified, setting this flag ensures that the -# the rooms exist by creating them when the first user on the -# homeserver registers. -# -# By default the auto-created rooms are publicly joinable from any federated -# server. Use the autocreate_auto_join_rooms_federated and -# autocreate_auto_join_room_preset settings below to customise this behaviour. -# -# Setting to false means that if the rooms are not manually created, -# users cannot be auto-joined since they do not exist. -# -# Defaults to true. Uncomment the following line to disable automatically -# creating auto-join rooms. -# -#autocreate_auto_join_rooms: false - -# Whether the auto_join_rooms that are auto-created are available via -# federation. Only has an effect if autocreate_auto_join_rooms is true. -# -# Note that whether a room is federated cannot be modified after -# creation. -# -# Defaults to true: the room will be joinable from other servers. -# Uncomment the following to prevent users from other homeservers from -# joining these rooms. -# -#autocreate_auto_join_rooms_federated: false - -# The room preset to use when auto-creating one of auto_join_rooms. Only has an -# effect if autocreate_auto_join_rooms is true. -# -# This can be one of "public_chat", "private_chat", or "trusted_private_chat". -# If a value of "private_chat" or "trusted_private_chat" is used then -# auto_join_mxid_localpart must also be configured. -# -# Defaults to "public_chat", meaning that the room is joinable by anyone, including -# federated servers if autocreate_auto_join_rooms_federated is true (the default). -# Uncomment the following to require an invitation to join these rooms. -# -#autocreate_auto_join_room_preset: private_chat - -# The local part of the user id which is used to create auto_join_rooms if -# autocreate_auto_join_rooms is true. If this is not provided then the -# initial user account that registers will be used to create the rooms. -# -# The user id is also used to invite new users to any auto-join rooms which -# are set to invite-only. -# -# It *must* be configured if autocreate_auto_join_room_preset is set to -# "private_chat" or "trusted_private_chat". -# -# Note that this must be specified in order for new users to be correctly -# invited to any auto-join rooms which have been set to invite-only (either -# at the time of creation or subsequently). -# -# Note that, if the room already exists, this user must be joined and -# have the appropriate permissions to invite new members. -# -#auto_join_mxid_localpart: system - -# When auto_join_rooms is specified, setting this flag to false prevents -# guest accounts from being automatically joined to the rooms. -# -# Defaults to true. -# -#auto_join_rooms_for_guests: false - -# Whether to inhibit errors raised when registering a new account if the user ID -# already exists. If turned on, that requests to /register/available will always -# show a user ID as available, and Synapse won't raise an error when starting -# a registration with a user ID that already exists. However, Synapse will still -# raise an error if the registration completes and the username conflicts. -# -# Defaults to false. -# -#inhibit_user_in_use_error: true - - -## Metrics ### +Time that a refresh token remains valid for (provided that it is not +exchanged for another one first). +This option can be used to automatically log-out inactive sessions. +Please see the manual for more information. -# Enable collection and rendering of performance metrics -# -#enable_metrics: false - -# Enable sentry integration -# NOTE: While attempts are made to ensure that the logs don't contain -# any sensitive information, this cannot be guaranteed. By enabling -# this option the sentry server may therefore receive sensitive -# information, and it in turn may then diseminate sensitive information -# through insecure notification channels if so configured. -# -#sentry: -# dsn: "..." - -# Flags to enable Prometheus metrics which are not suitable to be -# enabled by default, either for performance reasons or limited use. -# -metrics_flags: - # Publish synapse_federation_known_servers, a gauge of the number of - # servers this homeserver knows about, including itself. May cause - # performance problems on large homeservers. - # - #known_servers: true - -# Whether or not to report anonymized homeserver usage statistics. -# -#report_stats: true|false +Note also that this is calculated at login time and refresh time: +changes are not applied to existing sessions until they are refreshed. -# The endpoint to report the anonymized homeserver usage statistics to. -# Defaults to https://matrix.org/report-usage-stats/push -# -#report_stats_endpoint: https://example.com/report-usage-stats/push +By default, this is infinite. +Example usage: +``` +refresh_token_lifetime: 24h +``` +--- +Config option: `nonrefreshable_access_token_lifetime` -## API Configuration ## +Time that an access token remains valid for, if the session is NOT +using refresh tokens. -# Controls for the state that is shared with users who receive an invite -# to a room -# -room_prejoin_state: - # By default, the following state event types are shared with users who - # receive invites to the room: - # - # - m.room.join_rules - # - m.room.canonical_alias - # - m.room.avatar - # - m.room.encryption - # - m.room.name - # - m.room.create - # - m.room.topic - # - # Uncomment the following to disable these defaults (so that only the event - # types listed in 'additional_event_types' are shared). Defaults to 'false'. - # - #disable_default_event_types: true - - # Additional state event types to share with users when they are invited - # to a room. - # - # By default, this list is empty (so only the default event types are shared). - # - #additional_event_types: - # - org.example.custom.event.type - -# We record the IP address of clients used to access the API for various -# reasons, including displaying it to the user in the "Where you're signed in" -# dialog. -# -# By default, when puppeting another user via the admin API, the client IP -# address is recorded against the user who created the access token (ie, the -# admin user), and *not* the puppeted user. -# -# Uncomment the following to also record the IP address against the puppeted -# user. (This also means that the puppeted user will count as an "active" user -# for the purpose of monthly active user tracking - see 'limit_usage_by_mau' etc -# above.) -# -#track_puppeted_user_ips: true - - -# A list of application service config files to use -# -#app_service_config_files: -# - app_service_1.yaml -# - app_service_2.yaml - -# Uncomment to enable tracking of application service IP addresses. Implicitly -# enables MAU tracking for application service users. -# -#track_appservice_user_ips: true - - -# a secret which is used to sign access tokens. If none is specified, -# the registration_shared_secret is used, if one is given; otherwise, -# a secret key is derived from the signing key. -# -#macaroon_secret_key: - -# a secret which is used to calculate HMACs for form values, to stop -# falsification of values. Must be specified for the User Consent -# forms to work. -# -#form_secret: +Please note that not all clients support refresh tokens, so setting +this to a short value may be inconvenient for some users who will +then be logged out frequently. -## Signing Keys ## +Note also that this is calculated at login time: changes are not applied +retrospectively to existing sessions for users that have already logged in. -# Path to the signing key to sign messages with -# -signing_key_path: "CONFDIR/SERVERNAME.signing.key" +By default, this is infinite. -# The keys that the server used to sign messages with but won't use -# to sign new messages. -# -old_signing_keys: - # For each key, `key` should be the base64-encoded public key, and - # `expired_ts`should be the time (in milliseconds since the unix epoch) that - # it was last used. - # - # It is possible to build an entry from an old signing.key file using the - # `export_signing_key` script which is provided with synapse. - # - # For example: - # - #"ed25519:id": { key: "base64string", expired_ts: 123456789123 } - -# How long key response published by this server is valid for. -# Used to set the valid_until_ts in /key/v2 APIs. -# Determines how quickly servers will query to check which keys -# are still valid. -# -#key_refresh_interval: 1d - -# The trusted servers to download signing keys from. -# -# When we need to fetch a signing key, each server is tried in parallel. -# -# Normally, the connection to the key server is validated via TLS certificates. -# Additional security can be provided by configuring a `verify key`, which -# will make synapse check that the response is signed by that key. -# -# This setting supercedes an older setting named `perspectives`. The old format -# is still supported for backwards-compatibility, but it is deprecated. -# -# 'trusted_key_servers' defaults to matrix.org, but using it will generate a -# warning on start-up. To suppress this warning, set -# 'suppress_key_server_warning' to true. -# -# Options for each entry in the list include: -# -# server_name: the name of the server. required. -# -# verify_keys: an optional map from key id to base64-encoded public key. -# If specified, we will check that the response is signed by at least -# one of the given keys. -# -# accept_keys_insecurely: a boolean. Normally, if `verify_keys` is unset, -# and federation_verify_certificates is not `true`, synapse will refuse -# to start, because this would allow anyone who can spoof DNS responses -# to masquerade as the trusted key server. If you know what you are doing -# and are sure that your network environment provides a secure connection -# to the key server, you can set this to `true` to override this -# behaviour. -# -# An example configuration might look like: -# -#trusted_key_servers: -# - server_name: "my_trusted_server.example.com" -# verify_keys: -# "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr" -# - server_name: "my_other_trusted_server.example.com" -# -trusted_key_servers: - - server_name: "matrix.org" +Example usage: +``` +nonrefreshable_access_token_lifetime: 24h +``` +--- +Config option: `registrations_require_3pid` -# Uncomment the following to disable the warning that is emitted when the -# trusted_key_servers include 'matrix.org'. See above. -# -#suppress_key_server_warning: true +If this is set, the user must provide all of the specified types of 3PID when registering. -# 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. -# -#key_server_signing_keys_path: "key_server_signing_keys.key" +Example usage: +``` +registrations_require_3pid: + - email + - msisdn +``` +--- +Config option: `disable_msisdn_registration` +Explicitly disable asking for MSISDNs from the registration +flow (overrides `registrations_require_3pid` if MSISDNs are set as required) -## Single sign-on integration ## +Example usage: +``` +disable_msisdn_registration: true +``` +--- +Config option: `allowed_local_3pids` -# 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 -# * password_config.enabled -# -# You will also want to investigate the settings under the "sso" configuration -# section below. - -# Enable SAML2 for registration and login. Uses pysaml2. -# -# At least one of `sp_config` or `config_path` must be set in this section to -# enable SAML login. -# -# Once SAML support is enabled, a metadata file will be exposed at -# https://:/_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://:/_synapse/client/saml2/authn_response. -# -saml2_config: - # `sp_config` is 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. - # - sp_config: - # 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. - # - #metadata: - # local: ["saml2/idp.xml"] - # remote: - # - url: https://our_idp/metadata.xml - - # Allowed clock difference in seconds between the homeserver and IdP. - # - # Uncomment the below to increase the accepted time difference from 0 to 3 seconds. - # - #accepted_time_diff: 3 - - # By default, the user has to go to our login page first. If you'd like - # to allow IdP-initiated login, set 'allow_unsolicited: true' in a - # 'service.sp' section: - # - #service: - # sp: - # allow_unsolicited: true +Mandate that users are only allowed to associate certain formats of +3PIDs with accounts on this server, as specified by the `medium` and `pattern` settings. - # 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! +Example usage: +``` +allowed_local_3pids: + - medium: email + pattern: '^[^@]+@matrix\.org$' + - medium: email + pattern: '^[^@]+@vector\.im$' + - medium: msisdn + pattern: '\+44' +``` +--- +Config option: `enable_3pid_lookup` - #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 - - # Instead of putting the config inline as above, you can specify a - # separate pysaml2 configuration file: - # - #config_path: "CONFDIR/sp_conf.py" +Enable 3PIDs lookup requests to identity servers from this server. Defaults to true. - # 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. - # - #saml_session_lifetime: 5m +Example usage: +``` +enable_3pid_lookup: false +``` +--- +Config option: `registration_requires_token` - # An external module can be provided here as a custom solution to - # mapping attributes returned from a saml provider onto a matrix user. - # - user_mapping_provider: - # The custom module's class. Uncomment to use a custom module. - # - #module: mapping_provider.SamlMappingProvider - - # Custom configuration values for the module. Below options are - # intended for the built-in provider, they should be changed if - # using a custom module. This section will be passed as a Python - # dictionary to the module's `parse_config` method. - # - config: - # The SAML attribute (after mapping via the attribute maps) to use - # to derive the Matrix ID from. '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_source_attribute: displayName - - # The mapping system to use for mapping the saml attribute onto a - # matrix ID. - # - # Options include: - # * 'hexencode' (which maps unpermitted characters to '=xx') - # * '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. - # - #mxid_mapping: dotreplace - - # 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'. - # - #grandfathered_mxid_source_attribute: upn +Require users to submit a token during registration. +Tokens can be managed using the admin API: +https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html +Note that `enable_registration` must be set to `true`. +Disabling this option will not delete any tokens previously generated. +Defaults to false. Set to true to enable. - # 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 below. All of the listed attributes must - # match for the login to be permitted. - # - #attribute_requirements: - # - attribute: userGroup - # value: "staff" - # - attribute: department - # value: "sales" - - # 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. - # - #idp_entityid: 'https://our_idp/entityid' - - -# List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration -# and login. -# -# 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:///. (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 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'. -# -# 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'. -# -# 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. -# -# 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 https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#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_claim: name of the claim containing a unique identifier -# for the user. Defaults to 'sub', which OpenID Connect -# compliant providers should provide. -# -# 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 'sso_auth_account_details.html' in the 'sso' -# section of this file). -# -# 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. -# -# 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 below. 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 -# below, the `family_name` claim MUST be "Stephensson", but the `groups` -# claim MUST contain "admin". -# -# attribute_requirements: -# - attribute: family_name -# value: "Stephensson" -# - attribute: groups -# value: "admin" -# -# See https://matrix-org.github.io/synapse/latest/openid.html -# 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.) -# -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 - # 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" - - -# Enable Central Authentication Service (CAS) for registration and login. -# -cas_config: - # Uncomment the following to enable authorization against a CAS server. - # Defaults to false. - # - #enabled: true +Example usage: +``` +registration_requires_token: true +``` +--- +Config option: `registration_shared_secret` - # The URL of the CAS authorization endpoint. - # - #server_url: "https://cas-server.com" +If set, allows registration of standard or admin accounts by anyone who +has the shared secret, even if registration is otherwise disabled. - # The attribute of the CAS response to use as the display name. - # - # If unset, no displayname will be set. - # - #displayname_attribute: name +Example usage: +``` +registration_shared_secret: +``` +--- +Config option: `bcrypt_rounds` - # It is possible to configure Synapse to only allow logins if CAS attributes - # match particular values. All of the keys in the mapping 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. - # - #required_attributes: - # userGroup: "staff" - # department: None +Set the number of bcrypt rounds used to generate password hash. +Larger numbers increase the work factor needed to generate the hash. +The default number is 12 (which equates to 2^12 rounds). +N.B. that increasing this will exponentially increase the time required +to register or login - e.g. 24 => 2^24 rounds which will take >20 mins. +Example usage: +``` +bcrypt_rounds: 14 +``` +--- +Config option: `allow_guest_access` +Allows users to register as guests without a password/email/etc, and +participate in rooms hosted on this server which have been made +accessible to anonymous users. Defaults to false. -# 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 -# https://matrix-org.github.io/synapse/latest/templates.html for more information. -# -sso: - # 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. - # - #client_whitelist: - # - https://riot.im/develop - # - https://my.custom.client/ - - # Uncomment 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. - # - #update_profile_information: true - - -# 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 https://matrix-org.github.io/synapse/latest/jwt.html. -# -#jwt_config: - # Uncomment the following to enable authorization using JSON web - # tokens. Defaults to false. - # - #enabled: true - - # 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 true. - # - #secret: "provided-by-your-issuer" - - # The algorithm used to sign the JSON web token. - # - # Supported algorithms are listed at - # https://pyjwt.readthedocs.io/en/latest/algorithms.html - # - # Required if 'enabled' is true. - # - #algorithm: "provided-by-your-issuer" - - # Name of the claim containing a unique identifier for the user. - # - # Optional, defaults to `sub`. - # - #subject_claim: "sub" - - # The issuer to validate the "iss" claim against. - # - # Optional, if provided the "iss" claim will be required and - # validated for all JSON web tokens. - # - #issuer: "provided-by-your-issuer" - - # 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. - # - #audiences: - # - "provided-by-your-issuer" +Example usage: +``` +allow_guest_access: true +``` +--- +Config option: `default_identity_server` +The identity server which we suggest that clients should use when users log +in on this server. -password_config: - # Uncomment to disable password login - # - #enabled: false - - # Uncomment 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. - # - #localdb_enabled: false - - # Uncomment and change to a secret random string for extra security. - # DO NOT CHANGE THIS AFTER INITIAL SETUP! - # - #pepper: "EVEN_MORE_SECRET" - - # Define and enforce a password policy. Each parameter is optional. - # This is an implementation of MSC2000. - # - policy: - # Whether to enforce the password policy. - # Defaults to 'false'. - # - #enabled: true - - # Minimum accepted length for a password. - # Defaults to 0. - # - #minimum_length: 15 - - # Whether a password must contain at least one digit. - # Defaults to 'false'. - # - #require_digit: true - - # 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_symbol: true - - # Whether a password must contain at least one lowercase letter. - # Defaults to 'false'. - # - #require_lowercase: true - - # Whether a password must contain at least one uppercase letter. - # Defaults to 'false'. - # - #require_uppercase: true +(By default, no suggestion is made, so it is left up to the client. +This setting is ignored unless `public_baseurl` is also explicitly set.) -ui_auth: - # The amount of time to allow a user-interactive authentication session - # to be active. - # - # This defaults to 0, meaning the user is queried for their credentials - # before every action, but this can be overridden to allow a single - # validation to be re-used. This weakens the protections afforded by - # the user-interactive authentication process, by allowing for multiple - # (and potentially different) operations to use the same validation session. - # - # This is ignored for potentially "dangerous" operations (including - # deactivating an account, modifying an account password, and - # adding a 3PID). - # - # Uncomment below to allow for credential validation to last for 15 - # seconds. - # - #session_timeout: "15s" - - -# Configuration for sending emails from Synapse. -# -# Server admins can configure custom templates for email content. See -# https://matrix-org.github.io/synapse/latest/templates.html for more information. -# -email: - # The hostname of the outgoing SMTP server to use. Defaults to 'localhost'. - # - #smtp_host: mail.server +Example usage: +``` +default_identity_server: https://matrix.org +``` +--- +Config option: `account_threepid_delegates` - # The port on the mail server for outgoing SMTP. Defaults to 25. - # - #smtp_port: 587 +Handle threepid (email/phone etc) registration and password resets through a set of +*trusted* identity servers. Note that this allows the configured identity server to +reset passwords for accounts! - # Username/password for authentication to the SMTP server. By default, no - # authentication is attempted. - # - #smtp_user: "exampleusername" - #smtp_pass: "examplepassword" +Be aware that if `email` is not set, and SMTP options have not been +configured in the email config block, registration and user password resets via +email will be globally disabled. - # Uncomment the following to require TLS transport security for SMTP. - # By default, Synapse will connect over plain text, and will then switch to - # TLS via STARTTLS *if the SMTP server supports it*. If this option is set, - # Synapse will refuse to connect unless the server supports STARTTLS. - # - #require_transport_security: true +Additionally, if `msisdn` is not set, registration and password resets via msisdn +will be disabled regardless, and users will not be able to associate an msisdn +identifier to their account. This is due to Synapse currently not supporting +any method of sending SMS messages on its own. - # Uncomment the following to disable TLS for SMTP. - # - # By default, if the server supports TLS, it will be used, and the server - # must present a certificate that is valid for 'smtp_host'. If this option - # is set to false, TLS will not be used. - # - #enable_tls: false +To enable using an identity server for operations regarding a particular third-party +identifier type, set the value to the URL of that identity server as shown in the +examples below. - # notif_from defines the "From" address to use when sending emails. - # It must be set if email sending is enabled. - # - # The placeholder '%(app)s' will be replaced by the application name, - # which is normally 'app_name' (below), but may be overridden by the - # Matrix client application. - # - # Note that the placeholder must be written '%(app)s', including the - # trailing 's'. - # - #notif_from: "Your Friendly %(app)s homeserver " +Servers handling the these requests must answer the `/requestToken` endpoints defined +by the Matrix Identity Service API specification: +https://matrix.org/docs/spec/identity_service/latest - # app_name defines the default value for '%(app)s' in notif_from and email - # subjects. It defaults to 'Matrix'. - # - #app_name: my_branded_matrix_server +Example usage: +``` +account_threepid_delegates: + email: https://example.com # Delegate email sending to example.com + msisdn: http://localhost:8090 # Delegate SMS sending to this local process +``` +--- +Config option: `enable_set_displayname` - # Uncomment the following to enable sending emails for messages that the user - # has missed. Disabled by default. - # - #enable_notifs: true +Whether users are allowed to change their displayname after it has +been initially set. Useful when provisioning users based on the +contents of a third-party directory. - # Uncomment the following to disable automatic subscription to email - # notifications for new users. Enabled by default. - # - #notif_for_new_users: false +Does not apply to server administrators. Defaults to true. - # Custom URL for client links within the email notifications. By default - # links will be based on "https://matrix.to". - # - # (This setting used to be called riot_base_url; the old name is still - # supported for backwards-compatibility but is now deprecated.) - # - #client_base_url: "http://localhost/riot" +Example usage: +``` +enable_set_displayname: false +``` +--- +Config option: `enable_set_avatar_url` - # Configure the time that a validation email will expire after sending. - # Defaults to 1h. - # - #validation_token_lifetime: 15m +Whether users are allowed to change their avatar after it has been +initially set. Useful when provisioning users based on the contents +of a third-party directory. - # The web client location to direct users to during an invite. This is passed - # to the identity server as the org.matrix.web_client_location key. Defaults - # to unset, giving no guidance to the identity server. - # - #invite_client_location: https://app.element.io +Does not apply to server administrators. Defaults to true. - # Subjects to use when sending emails from Synapse. - # - # The placeholder '%(app)s' will be replaced with the value of the 'app_name' - # setting above, or by a value dictated by the Matrix client application. - # - # If a subject isn't overridden in this configuration file, the value used as - # its example will be used. - # - #subjects: - - # Subjects for notification emails. - # - # On top of the '%(app)s' placeholder, these can use the following - # placeholders: - # - # * '%(person)s', which will be replaced by the display name of the user(s) - # that sent the message(s), e.g. "Alice and Bob". - # * '%(room)s', which will be replaced by the name of the room the - # message(s) have been sent to, e.g. "My super room". - # - # See the example provided for each setting to see which placeholder can be - # used and how to use them. - # - # Subject to use to notify about one message from one or more user(s) in a - # room which has a name. - #message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..." - # - # Subject to use to notify about one message from one or more user(s) in a - # room which doesn't have a name. - #message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..." - # - # Subject to use to notify about multiple messages from one or more users in - # a room which doesn't have a name. - #messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..." - # - # Subject to use to notify about multiple messages in a room which has a - # name. - #messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..." - # - # Subject to use to notify about multiple messages in multiple rooms. - #messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..." - # - # Subject to use to notify about multiple messages from multiple persons in - # multiple rooms. This is similar to the setting above except it's used when - # the room in which the notification was triggered has no name. - #messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..." - # - # Subject to use to notify about an invite to a room which has a name. - #invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..." - # - # Subject to use to notify about an invite to a room which doesn't have a - # name. - #invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..." - - # Subject for emails related to account administration. - # - # On top of the '%(app)s' placeholder, these one can use the - # '%(server_name)s' placeholder, which will be replaced by the value of the - # 'server_name' setting in your Synapse configuration. - # - # Subject to use when sending a password reset email. - #password_reset: "[%(server_name)s] Password reset" - # - # Subject to use when sending a verification email to assert an address's - # ownership. - #email_validation: "[%(server_name)s] Validate your email" +Example usage: +``` +enable_set_avatar_url: false +``` +--- +Config option: `enable_3pid_changes` +Whether users can change the third-party IDs associated with their accounts +(email address and msisdn). +Defaults to true. -## Push ## +Example usage: +``` +enable_3pid_changes: false +``` +--- +Config option: `auto_join_rooms` -push: - # 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 former, this option controls whether the - # notification request includes the content of the event (other details - # like the sender are still included). For `event_id_only` push, 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. - # - # The default value is "true" to include message details. Uncomment to only - # include the event ID and room ID in push notification payloads. - # - #include_content: false +Users who register on this homeserver will automatically be joined +to the rooms listed under this option. - # 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. - # - # The default value is "true", meaning push clients will see the number of - # rooms with unread messages in them. Uncomment to instead send the number - # of unread messages. +By default, any room aliases included in this list will be created +as a publicly joinable room when the first user registers for the +homeserver. If the room already exists, make certain it is a publicly joinable +room, i.e. the join rule of the room must be set to 'public'. You can find more options +relating to auto-joining rooms below. + +Example usage: +``` +auto_join_rooms: + - "#exampleroom:example.com" + - "#anotherexampleroom:example.com" +``` +--- +Config option: `autocreate_auto_join_rooms` + +Where `auto_join_rooms` are specified, setting this flag ensures that +the rooms exist by creating them when the first user on the +homeserver registers. + +By default the auto-created rooms are publicly joinable from any federated +server. Use the `autocreate_auto_join_rooms_federated` and +`autocreate_auto_join_room_preset` settings below to customise this behaviour. + +Setting to false means that if the rooms are not manually created, +users cannot be auto-joined since they do not exist. + +Defaults to true. + +Example usage: +``` +autocreate_auto_join_rooms: false +``` +--- +Config option: `autocreate_auto_join_rooms_federated` + +Whether the rooms listen in `auto_join_rooms` that are auto-created are available +via federation. Only has an effect if `autocreate_auto_join_rooms` is true. + +Note that whether a room is federated cannot be modified after +creation. + +Defaults to true: the room will be joinable from other servers. +Set to false to prevent users from other homeservers from +joining these rooms. + +Example usage: +``` +autocreate_auto_join_rooms_federated: false +``` +--- +Config option: `autocreate_auto_join_room_preset` + +The room preset to use when auto-creating one of `auto_join_rooms`. Only has an +effect if `autocreate_auto_join_rooms` is true. + +Possible values for this option are: +* "public_chat": the room is joinable by anyone, including + federated servers if `autocreate_auto_join_rooms_federated` is true (the default). +* "private_chat": an invitation is required to join these rooms. +* "trusted_private_chat": an invitation is required to join this room and the invitee is + assigned a power level of 100 upon joining the room. + +If a value of "private_chat" or "trusted_private_chat" is used then +`auto_join_mxid_localpart` must also be configured. + +Defaults to "public_chat". + +Example usage: +``` +autocreate_auto_join_room_preset: private_chat +``` +--- +Config option: `auto_join_mxid_localpart` + +The local part of the user id which is used to create `auto_join_rooms` if +`autocreate_auto_join_rooms` is true. If this is not provided then the +initial user account that registers will be used to create the rooms. + +The user id is also used to invite new users to any auto-join rooms which +are set to invite-only. + +It *must* be configured if `autocreate_auto_join_room_preset` is set to +"private_chat" or "trusted_private_chat". + +Note that this must be specified in order for new users to be correctly +invited to any auto-join rooms which have been set to invite-only (either +at the time of creation or subsequently). + +Note that, if the room already exists, this user must be joined and +have the appropriate permissions to invite new members. + +Example usage: +``` +auto_join_mxid_localpart: system +``` +--- +Config option: `auto_join_rooms_for_guests` + +When `auto_join_rooms` is specified, setting this flag to false prevents +guest accounts from being automatically joined to the rooms. + +Defaults to true. + +Example usage: +``` +auto_join_rooms_for_guests: false +``` +--- +Config option: `inhibit_user_in_use_error` + +Whether to inhibit errors raised when registering a new account if the user ID +already exists. If turned on, requests to `/register/available` will always +show a user ID as available, and Synapse won't raise an error when starting +a registration with a user ID that already exists. However, Synapse will still +raise an error if the registration completes and the username conflicts. + +Defaults to false. + +Example usage: +``` +inhibit_user_in_use_error: true +``` +--- +## Metrics ### +Config options related to metrics. + +--- +Config option: `enable_metrics` + +Set to true to enable collection and rendering of performance metrics. +Defaults to false. + +Example usage: +``` +enable_metrics: true +``` +--- +Config option: `sentry` + +Use this option to enable sentry integration. Provide the DSN assigned to you by sentry +with the `dsn` setting. + +NOTE: While attempts are made to ensure that the logs don't contain +any sensitive information, this cannot be guaranteed. By enabling +this option the sentry server may therefore receive sensitive +information, and it in turn may then disseminate sensitive information +through insecure notification channels if so configured. + +Example usage: +``` +sentry: + dsn: "..." +``` +--- +Config option: `metrics_flags` + +Flags to enable Prometheus metrics which are not suitable to be +enabled by default, either for performance reasons or limited use. +Currently the only option is `known_servers`, which publishes +`synapse_federation_known_servers`, a gauge of the number of +servers this homeserver knows about, including itself. May cause +performance problems on large homeservers. + +Example usage: +``` +metrics_flags: + known_servers: true +``` +--- +Config option: `report_stats` + +Whether or not to report anonymized homeserver usage statistics. This is originally +set when generating the config. Set this option to true or false to change the current +behavior. + +Example usage: +``` +report_stats: true +``` +--- +Config option: `report_stats_endpoint` + +The endpoint to report the anonymized homeserver usage statistics to. +Defaults to https://matrix.org/report-usage-stats/push + +Example usage: +``` +report_stats_endpoint: https://example.com/report-usage-stats/push +``` +--- +## API Configuration ## +Config settings related to the client/server API + +--- +Config option: `room_prejoin_state:` + +Controls for the state that is shared with users who receive an invite +to a room. By default, the following state event types are shared with users who +receive invites to the room: +- m.room.join_rules +- m.room.canonical_alias +- m.room.avatar +- m.room.encryption +- m.room.name +- m.room.create +- m.room.topic + +To change the default behavior, use the following options: +* `disable_default_event_types`: set to true to disable the above defaults. If this + is enabled, only the event types listed in `additional_event_types` are shared. + Defaults to false. +* `additional_event_types`: Additional state event types to share with users when they are invited + to a room. By default, this list is empty (so only the default event types are shared). + +Example usage: +``` +room_prejoin_state: + disable_default_event_types: true + additional_event_types: + - org.example.custom.event.type + - m.room.join_rules +``` +--- +Config option: `track_puppeted_user_ips` + +We record the IP address of clients used to access the API for various +reasons, including displaying it to the user in the "Where you're signed in" +dialog. + +By default, when puppeting another user via the admin API, the client IP +address is recorded against the user who created the access token (ie, the +admin user), and *not* the puppeted user. + +Set this option to true to also record the IP address against the puppeted +user. (This also means that the puppeted user will count as an "active" user +for the purpose of monthly active user tracking - see `limit_usage_by_mau` etc +above.) + +Example usage: +``` +track_puppeted_user_ips: true +``` +--- +Config option: `app_service_config_files` + +A list of application service config files to use. + +Example usage: +``` +app_service_config_files: + - app_service_1.yaml + - app_service_2.yaml +``` +--- +Config option: `track_appservice_user_ips` + +Defaults to false. Set to true to enable tracking of application service IP addresses. +Implicitly enables MAU tracking for application service users. + +Example usage: +``` +track_appservice_user_ips: true +``` +--- +Config option: `macaroon_secret_key` + +A secret which is used to sign access tokens. If none is specified, +the `registration_shared_secret` is used, if one is given; otherwise, +a secret key is derived from the signing key. + +Example usage: +``` +macaroon_secret_key: +``` +--- +Config option: `form_secret` + +A secret which is used to calculate HMACs for form values, to stop +falsification of values. Must be specified for the User Consent +forms to work. + +Example usage: +``` +form_secret: +``` +--- +## Signing Keys ## +Config options relating to signing keys + +--- +Config option: `signing_key_path` + +Path to the signing key to sign messages with. + +Example usage: +``` +signing_key_path: "CONFDIR/SERVERNAME.signing.key" +``` +--- +Config option: `old_signing_keys` + +The keys that the server used to sign messages with but won't use +to sign new messages. For each key, `key` should be the base64-encoded public key, and +`expired_ts`should be the time (in milliseconds since the unix epoch) that +it was last used. + +It is possible to build an entry from an old `signing.key` file using the +`export_signing_key` script which is provided with synapse. + +Example usage: +``` +old_signing_keys: + "ed25519:id": { key: "base64string", expired_ts: 123456789123 } +``` +--- +Config option: `key_refresh_interval` + +How long key response published by this server is valid for. +Used to set the `valid_until_ts` in `/key/v2` APIs. +Determines how quickly servers will query to check which keys +are still valid. Defaults to 1d. + +Example usage: +``` +key_refresh_interval: 2d +``` +--- +Config option: `trusted_key_servers:` + +The trusted servers to download signing keys from. + +When we need to fetch a signing key, each server is tried in parallel. + +Normally, the connection to the key server is validated via TLS certificates. +Additional security can be provided by configuring a `verify key`, which +will make synapse check that the response is signed by that key. + +This setting supercedes an older setting named `perspectives`. The old format +is still supported for backwards-compatibility, but it is deprecated. + +`trusted_key_servers` defaults to matrix.org, but using it will generate a +warning on start-up. To suppress this warning, set +`suppress_key_server_warning` to true. + +Options for each entry in the list include: +* `server_name`: the name of the server. required. +* `verify_keys`: an optional map from key id to base64-encoded public key. + If specified, we will check that the response is signed by at least + one of the given keys. +* `accept_keys_insecurely`: a boolean. Normally, if `verify_keys` is unset, + and `federation_verify_certificates` is not `true`, synapse will refuse + to start, because this would allow anyone who can spoof DNS responses + to masquerade as the trusted key server. If you know what you are doing + and are sure that your network environment provides a secure connection + to the key server, you can set this to `true` to override this behaviour. + +Example usage #1: +``` +trusted_key_servers: + - server_name: "my_trusted_server.example.com" + verify_keys: + "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr" + - server_name: "my_other_trusted_server.example.com" +``` +Example usage #1: +``` +trusted_key_servers: + - server_name: "matrix.org" +``` +--- +Config option: `suppress_key_server_warning` + +Set the following to true to disable the warning that is emitted when the +`trusted_key_servers` include 'matrix.org'. See above. + +Example usage: +``` +suppress_key_server_warning: true +``` +--- +Config option: `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 usage: +``` +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 + * password_config.enabled + +You will also want to investigate the settings under the "sso" configuration +section below. +--- +Config option: `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 option `config_path`. +* `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 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://:/_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://:/_synapse/client/saml2/authn_response`. + +Example configuration: +``` +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' +``` +--- +Config option: `oidc_providers` + +List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration +and login. See https://matrix-org.github.io/synapse/latest/openid.html +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:///. (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'. + +* `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`. + +* `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. + +* `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 https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#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_claim: name of the claim containing a unique identifier + for the user. Defaults to 'sub', which OpenID Connect + compliant providers should provide. + + * `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. + + +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: +``` +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: +``` +oidc_providers: + # Generic example # - #group_unread_count_by_room: false + - 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 + 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" +``` +--- +Config option: `cas_config` + +Enable Central Authentication Service (CAS) for registration and login. +Has the following options: +* `enabled`: Set this to true to enable authorization against a CAS server. + Defaults to false. +* `server_url`: The URL of the CAS authorization endpoint. +* `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. + +Example configuration: +``` +cas_config: + enabled: true + server_url: "https://cas-server.com" + displayname_attribute: name + required_attributes: + userGroup: "staff" + department: None +``` +--- +Config option: `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 +https://matrix-org.github.io/synapse/latest/templates.html 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: +``` +sso: + client_whitelist: + - https://riot.im/develop + - https://my.custom.client/ + update_profile_information: true +``` +--- +Config option: `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 https://matrix-org.github.io/synapse/latest/jwt.html. + +Additional 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 the JSON web token. Supported algorithms are listed at + https://pyjwt.readthedocs.io/en/latest/algorithms.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: +``` +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" +``` +--- +Config option: `password_config` + +* `enabled`: Defaults to true. +* `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. # Uncomment and change 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 usage: +``` +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 +``` +--- +Config option: `ui_auth` + +The amount of time to allow a user-interactive authentication session to be active. + +This defaults to 0, meaning the user is queried for their credentials +before every action, but this can be overridden to allow a single +validation to be re-used. This weakens the protections afforded by +the user-interactive authentication process, by allowing for multiple +(and potentially different) operations to use the same validation session. + +This is ignored for potentially "dangerous" operations (including +deactivating an account, modifying an account password, and +adding a 3PID). +Use the `session_timeout` sub-option here to change the time allowed for credential validation. +Example configuration: +``` +ui_auth: + session_timeout: "15s" +``` +--- +Config option: `email` + +Configuration for sending emails from Synapse. + +Server admins can configure custom templates for email content. See +https://matrix-org.github.io/synapse/latest/templates.html for more information. + +This option has the following subsections: +* `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'. +* `smtp_port`: The port on the mail server for outgoing SMTP. Defaults to 25. +* `smtp_user` and `smtp_pass`: Username/password for authentication to the SMTP server. By default, no + authentication is attempted. +* `require_transport_security`: Set to true to require TLS transport security for SMTP. + By default, Synapse will connect over plain text, and will then switch to + TLS via STARTTLS *if the SMTP server supports it*. If this option is set, + Synapse will refuse to connect unless the server supports STARTTLS. +* `enable_tls`: By default, if the server supports TLS, it will be used, and the server + must present a certificate that is valid for 'smtp_host'. If this option + is set to false, TLS will not be used. +* `notif_from`: defines the "From" address to use when sending emails. + It must be set if email sending is enabled. The placeholder '%(app)s' will be replaced by the application name, + which is normally set in `app_name`, but may be overridden by the + Matrix client application. Note that the placeholder must be written '%(app)s', including the + trailing 's'. +* `app_name`: `app_name` defines the default value for '%(app)s' in `notif_from` and email + subjects. It defaults to 'Matrix'. +* `enable_notifs`: Set to true to enable sending emails for messages that the user + has missed. Disabled by default. +* `notif_for_new_users`: Set to false to disable automatic subscription to email + notifications for new users. Enabled by default. +* `client_base_url`: Custom URL for client links within the email notifications. By default + links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`; + the old name is still supported for backwards-compatibility but is now deprecated.) +* `validation_token_lifetime`: Configures the time that a validation email will expire after sending. + Defaults to 1h. +* `invite_client_location`: The web client location to direct users to during an invite. This is passed + to the identity server as the `org.matrix.web_client_location` key. Defaults + to unset, giving no guidance to the identity server. +* `subjects`: Subjects to use when sending emails from Synapse. The placeholder '%(app)s' will + be replaced with the value of the `app_name` setting, or by a value dictated by the Matrix client application. + In addition, each subject can use the following placeholders: '%(person)s', which will be replaced by the displayname + of the user(s) that sent the message(s), e.g. "Alice and Bob", and '%(room)s', which will be replaced by the name of the room the + message(s) have been sent to, e.g. "My super room". In addition, emails related to account administration will + can use the '%(server_name)s' placeholder, which will be replaced by the value of the + `server_name` setting in your Synapse configuration. + + Here is a list of subjects for notification emails that can be set: + * `message_from_person_in_room`: Subject to use to notify about one message from one or more user(s) in a + room which has a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..." + * `message_from_person`: Subject to use to notify about one message from one or more user(s) in a + room which doesn't have a name. Defaults to "[%(app)s] You have a message on %(app)s from %(person)s..." + * `messages_from_person`: Subject to use to notify about multiple messages from one or more users in + a room which doesn't have a name. Defaults to "[%(app)s] You have messages on %(app)s from %(person)s..." + * `messages_in_room`: Subject to use to notify about multiple messages in a room which has a + name. Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room..." + * `messages_in_room_and_others`: Subject to use to notify about multiple messages in multiple rooms. + Defaults to "[%(app)s] You have messages on %(app)s in the %(room)s room and others..." + * `messages_from_person_and_others`: Subject to use to notify about multiple messages from multiple persons in + multiple rooms. This is similar to the setting above except it's used when + the room in which the notification was triggered has no name. Defaults to + "[%(app)s] You have messages on %(app)s from %(person)s and others..." + * `invite_from_person_to_room`: Subject to use to notify about an invite to a room which has a name. + Defaults to "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..." + * `invite_from_person`: Subject to use to notify about an invite to a room which doesn't have a + name. Defaults to "[%(app)s] %(person)s has invited you to chat on %(app)s..." + * `password_reset`: Subject to use when sending a password reset email. Defaults to "[%(server_name)s] Password reset" + * `email_validation`: Subject to use when sending a verification email to assert an address's + ownership. Defaults to "[%(server_name)s] Validate your email" + +Example usage: +``` +email: + smtp_host: mail.server + smtp_port: 587 + smtp_user: "exampleusername" + smtp_pass: "examplepassword" + require_transport_security: true + enable_tls: false + notif_from: "Your Friendly %(app)s homeserver " + app_name: my_branded_matrix_server + enable_notifs: true + notif_for_new_users: false + client_base_url: "http://localhost/riot" + validation_token_lifetime: 15m + invite_client_location: https://app.element.io + + subjects: + message_from_person_in_room: "[%(app)s] You have a message on %(app)s from %(person)s in the %(room)s room..." + message_from_person: "[%(app)s] You have a message on %(app)s from %(person)s..." + messages_from_person: "[%(app)s] You have messages on %(app)s from %(person)s..." + messages_in_room: "[%(app)s] You have messages on %(app)s in the %(room)s room..." + messages_in_room_and_others: "[%(app)s] You have messages on %(app)s in the %(room)s room and others..." + messages_from_person_and_others: "[%(app)s] You have messages on %(app)s from %(person)s and others..." + invite_from_person_to_room: "[%(app)s] %(person)s has invited you to join the %(room)s room on %(app)s..." + invite_from_person: "[%(app)s] %(person)s has invited you to chat on %(app)s..." + password_reset: "[%(server_name)s] Password reset" + email_validation: "[%(server_name)s] Validate your email" +``` +--- +## Push ## +Configuration settings related to push notifications + +--- +Config option: `push` + +This option has a number of sub-options relating to push notifications. They are as follows: +* `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. + # TODO: is this still correct? + Defaults to true. to include message details. 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. + +Example usage: +``` +push: + include_content: false + group_unread_count_by_room: false +``` +--- ## Rooms ## +Config options relating to rooms. + +--- +Config option: `encryption_enabled_by_default` + +Controls whether locally-created rooms should be end-to-end encrypted by +default. + +Possible options are "all", "invite", and "off". They are defined as: -# 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. -# -#encryption_enabled_by_default_for_room_type: invite - - -# Uncomment to allow non-server-admin users to create groups on this server -# -#enable_group_creation: true - -# If enabled, non server admins can only create groups with local parts -# starting with this prefix -# -#group_creation_prefix: "unofficial_" - - - -# User Directory configuration -# +* `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 usage: +``` +encryption_enabled_by_default_for_room_type: invite +``` +--- +Config option: `enable_group_creation` + +Set to true to allow non-server-admin users to create groups on this server + +Example usage: +``` +enable_group_creation: true +``` +--- +Config option: `group_creation_prefix` + +If enabled/present, non-server admins can only create groups with local parts +starting with this prefix. +# todo: can I rip out this group setting? +Example usage: +``` +group_creation_prefix: "unofficial_" +``` +--- +Config option: `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 when searching + the user directory. 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 API following the instructions at + https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#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. + +Example usage: +``` user_directory: - # Defines whether users can search the user directory. If false then - # empty responses are returned to all queries. Defaults to true. - # - # Uncomment to disable the user directory. - # - #enabled: false - - # Defines whether to search all users visible to your HS when searching - # the user directory. 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 API following the instructions at - # https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/background_updates.html#run - # - # Uncomment to return search results containing all known users, even if that - # user does not share a room with the requester. - # - #search_all_users: true - - # Defines whether to prefer local users in search query results. - # If True, local users are more likely to appear above remote users - # when searching the user directory. Defaults to false. - # - # Uncomment to prefer local over remote users in user directory search - # results. - # - #prefer_local_users: true - - -# User Consent configuration -# -# for detailed instructions, see -# https://matrix-org.github.io/synapse/latest/consent_tracking.html -# -# Parts of this section are required if enabling the 'consent' resource under -# '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 -# '.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 -# 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". -# -#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 -# - - - -# Settings for local room and user statistics collection. See -# https://matrix-org.github.io/synapse/latest/room_and_user_statistics.html. -# -stats: - # Uncomment the following to disable room and user statistics. Note that doing - # so may cause certain features (such as the room directory) not to work - # correctly. - # - #enabled: false - - -# Server Notices room configuration -# -# Uncomment this section to enable a room which can be used to send notices -# from the server to users. It is a special room which cannot be left; notices -# come from a special "notices" user id. -# -# If you uncomment this section, you *must* define the system_mxid_localpart -# setting, which defines the id of the user which will be used to send the -# notices. -# -# It's also possible to override the room name, the display name of the -# "notices" user, and the avatar for the user. -# -#server_notices: -# system_mxid_localpart: notices -# system_mxid_display_name: "Server Notices" -# system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" -# room_name: "Server Notices" - - - -# Uncomment 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. -# -#enable_room_list_search: false - -# The `alias_creation` option controls who's 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 -# alias: Matches against the alias being created -# room_id: Matches against the room ID the alias is being pointed at -# action: Whether to "allow" or "deny" the request if the rule matches -# -# The default is: -# -#alias_creation_rules: -# - user_id: "*" -# alias: "*" -# room_id: "*" -# action: allow - -# 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 -# room_id: Matches against the room ID being published -# alias: Matches against any current local or canonical aliases -# associated with the room -# action: Whether to "allow" or "deny" the request if the rule matches -# -# The default is: -# -#room_list_publication_rules: -# - user_id: "*" -# alias: "*" -# room_id: "*" -# action: allow + enabled: false + search_all_users: true + prefer_local_users: true +``` +--- +Config option: `user_consent` + +For detailed instructions on user consent configuration, see +https://matrix-org.github.io/synapse/latest/consent_tracking.html + +Parts of this section are required if enabling the `consent` resource under +`listeners`, in particular `template_dir` and `version`. # TODO: link `listeners` + +* `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 + .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 ##TODO: link + 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 usage: +``` +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 +``` +--- +Config option: `stats` + +Settings for local room and user statistics collection. See +https://matrix-org.github.io/synapse/latest/room_and_user_statistics.html. + +* `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 usage: +``` +stats: + enabled: false +``` +--- +Config option: `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. +Other 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 usage: +``` +server_notices: + system_mxid_localpart: notices + system_mxid_display_name: "Server Notices" + system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ" + room_name: "Server Notices" +``` +--- +Config option: `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 usage: +``` +enable_room_list_search: false +``` +--- +Config option: `alias_creation` + +The `alias_creation` 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: +``` +alias_creation_rules: + - user_id: "bad_user" + alias: "spammy_alias" + room_id: "*" + action: deny +``` +--- +Config options: `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: +``` +room_list_publication_rules: + - user_id: "*" + alias: "*" + room_id: "*" + action: allow +``` +--- ## Opentracing ## +Configuration options related to Opentracing support. + +--- +Config option: `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). + +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 https://matrix-org.github.io/synapse/latest/opentracing.html. + 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/. -# These settings enable 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 other services which supports opentracing -# (specifically those implemented with Jaeger). -# +Example usage: +``` opentracing: - # tracing is disabled by default. Uncomment the following line to enable it. - # - #enabled: true - - # The list of homeservers we wish to send and receive span contexts and span baggage. - # See https://matrix-org.github.io/synapse/latest/opentracing.html. - # - # 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. - # - #homeserver_whitelist: - # - ".*" - - # 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. - # - #force_tracing_for_users: - # - "@user1:server_name" - # - "@user2:server_name" - - # 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/. - # - #jaeger_config: - # sampler: - # type: const - # param: 1 - # logging: - # false - + enabled: true + homeserver_whitelist: + - ".*" + force_tracing_for_users: + - "@user1:server_name" + - "@user2:server_name" + jaeger_config: + sampler: + type: const + param: 1 + logging: + false +``` +--- ## Workers ## +Configuration options related to workers. -# Disables sending of outbound federation transactions on the main process. -# Uncomment if using a federation sender worker. -# -#send_federation: false - -# It is possible to run multiple federation sender workers, in which case the -# work is balanced across them. -# -# This configuration must be shared between all federation sender workers, and if -# changed all federation sender workers must be stopped at the same time and then -# started, to ensure that all instances are running with the same config (otherwise -# events may be dropped). -# -#federation_sender_instances: -# - federation_sender1 - -# When using workers this should be a map from `worker_name` to the -# HTTP replication listener of the worker, if configured. -# -#instance_map: -# worker1: -# host: localhost -# port: 8034 - -# Experimental: When using workers you can define which workers should -# handle event persistence and typing notifications. Any worker -# specified here must also be in the `instance_map`. -# -#stream_writers: -# events: worker1 -# typing: worker1 - -# The worker that is used to run background tasks (e.g. cleaning up expired -# data). If not provided this defaults to the main process. -# -#run_background_tasks_on: worker1 - -# A shared secret used by the replication APIs to authenticate HTTP requests -# from workers. -# -# By default this is unused and traffic is not authenticated. -# -#worker_replication_secret: "" - - -# Configuration for Redis when using workers. This *must* be enabled when -# using workers (unless using old style direct TCP configuration). -# -redis: - # Uncomment the below to enable Redis support. - # - #enabled: true +--- +Config option: `send_federation` - # Optional host and port to use to connect to redis. Defaults to - # localhost and 6379 - # - #host: localhost - #port: 6379 +Controls sending of outbound federation transactions on the main process. +Set to false if using a federation sender worker. Defaults to true. - # Optional password if configured on the Redis instance - # - #password: +Example usage: +``` +send_federation: false +``` +--- +Config option: `federation_sender_instances` + +It is possible to run multiple federation sender workers, in which case the +work is balanced across them. Use this setting to list the senders. + +This configuration setting must be shared between all federation sender workers, and if +changed all federation sender workers must be stopped at the same time and then +started, to ensure that all instances are running with the same config (otherwise +events may be dropped). + +Example usage: +``` +federation_sender_instances: + - federation_sender1 +``` +--- +Config option: `instance_map` + +When using workers this should be a map from worker name to the +HTTP replication listener of the worker, if configured. + +Example usage: +``` +instance_map: + worker1: + host: localhost + port: 8034 +``` +--- +Config option: `stream_writers` + +Experimental: When using workers you can define which workers should +handle event persistence and typing notifications. Any worker +specified here must also be in the `instance_map`. + +Example usage: +``` +stream_writers: + events: worker1 + typing: worker1 +``` +--- +Config option: `run_background_task_on` + +The worker that is used to run background tasks (e.g. cleaning up expired +data). If not provided this defaults to the main process. + +Example usage: +``` +run_background_tasks_on: worker1 +``` +--- +Config option: `worker_replication_secret` + +A shared secret used by the replication APIs to authenticate HTTP requests +from workers. +By default this is unused and traffic is not authenticated. + +Example usage: +``` +worker_replication_secret: "secret_secret" +``` +Config option: `redis` + +Configuration for [Redis]() # TODO add link when using workers. This *must* be enabled when +using workers (unless using old style direct TCP configuration). +Has the following options: +* `enabled`: whether to use Redis support. Defaults to false. +* `host` and `port`: Optional host and port to use to connect to redis. Defaults to + localhost and 6379 +* `password`: Optional password if configured on the Redis instance. + +Example usage: +``` +redis: + enabled: true + host: localhost + port: 6379 + password: +``` +## Background Updates ## +Configuration settings related to background updates. + +--- +Config option: `background_updates` + +Background updates are database updates that are run in the background in batches. +The duration, minimum batch size, default batch size, whether to sleep between batches and if so, how long to +sleep can all be configured. This is helpful to speed up or slow down the updates. +Options are: +* `background_update_duration_ms`: How long in milliseconds to run a batch of background updates for. Defaults to 100. + Set a different time to change the default. +* `sleep_enabled`: Whether to sleep between updates. Defaults to true. Set to false to change the default. +* `sleep_duration_ms`: If sleeping between updates, how long in milliseconds to sleep for. Defaults to 1000. + Set a duration to change the default. +* `min_batch_size`: Minimum size a batch of background updates can be. Must be greater than 0. Defaults to 1. + Set a size to change the default. +* `default_batch_size`: The batch size to use for the first iteration of a new background update. The default is 100. + Set a size to change the default. + +Example configuration: +``` +background_updates: + background_update_duration_ms: 500 + sleep_enabled: false + sleep_duration_ms: 300 + min_batch_size: 10 + default_batch_size: 50 +``` \ No newline at end of file From 494a1f18f77fca7fe93a6fd75578c80acea491b7 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Sun, 3 Apr 2022 20:26:18 -0700 Subject: [PATCH 04/11] more editing --- .../configuration/config_documentation.md | 197 +++++++++++------- 1 file changed, 119 insertions(+), 78 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 32db000d0424..b4bd50ec397f 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -29,11 +29,43 @@ messages from the database after 5 minutes, rather than 5 months. ## Yaml The configuration file is a [YAML](https://yaml.org/) 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 a default (if available) will - apply. Thus, in the example below, -``` - -``` +* `#` 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 the `presence` 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 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: + ``` + 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. "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. ## Index [Modules](#modules) @@ -95,8 +127,11 @@ documentation on how to configure or create custom modules for Synapse. --- Config option: `modules` -Add modules under this option to extend functionality. Defaults -to none. +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: ``` @@ -131,6 +166,8 @@ 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: ``` @@ -143,7 +180,7 @@ server_name: localhost:8080 --- Config option: `pid_file` -When running Synapse as a daemon, the file to store the pid in. +When running Synapse as a daemon, the file to store the pid in. Defaults to none. Example configuration: ``` @@ -152,7 +189,7 @@ pid_file: DATADIR/homeserver.pid --- Config option: `web_client_location` -The absolute URL to the web client which `/` will redirect to. +The absolute URL to the web client which `/` will redirect to. Defaults to none. Example configuration: ``` @@ -184,7 +221,7 @@ Provided `https:///` on port 443 is routed to Synapse, this option configures Synapse to serve a file at `https:///.well-known/matrix/server`. This will tell other servers to send traffic to port 443 instead. -This option currently defaults to 'false'. +This option currently defaults to false. See https://matrix-org.github.io/synapse/latest/delegate.html for more information. @@ -198,17 +235,19 @@ 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: 0 +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. Uncomment the `enabled` flag below `presence` to -disable presence tracking on this homeserver. This option replaces the previous top-level 'use_presence' option. +of other local and remote users. Set the `enabled` flag below `presence` to false to +disable presence tracking on this homeserver. Defaults to true. +This option replaces the previous top-level 'use_presence' option. Example configuration: ``` @@ -219,7 +258,7 @@ presence: 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 +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: @@ -232,7 +271,7 @@ 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'. +requesting server. Defaults to false. Example configuration: ``` @@ -245,7 +284,7 @@ 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'. +Defaults to true. Example configuration: ``` @@ -254,9 +293,9 @@ 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 +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'. +query the room directory. Defaults to false. Example configuration: ``` @@ -265,8 +304,8 @@ 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'. +If set to true, allows any other homeserver to fetch the server's public +rooms directory via federation. Defaults to false. Example configuration: ``` @@ -277,22 +316,22 @@ Config option: `default_room_version` The default room version for newly created rooms on this server. -Known room versions are listed here: -https://spec.matrix.org/latest/rooms/#complete-list-of-room-versions +Known room versions are listed [here](https://spec.matrix.org/latest/rooms/#complete-list-of-room-versions) For example, for room version 1, `default_room_version` should be set to "1". -Currently defualts to "9". +Currently defaults to "9". Example configuration: ``` -default_room_version: "9" +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: ``` @@ -326,7 +365,7 @@ 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'. +(except those sent by local server admins). Defaults to false. Example configuration: ``` @@ -335,8 +374,8 @@ block_non_admin_invites: true --- Config option: `enable_search` -If disabled, new messages will not be indexed for searching and users -will receive errors when searching for messages. Defaults to enabled. +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: ``` @@ -345,7 +384,7 @@ enable_search: false --- Config option: `ip_range_blacklist` -This option prevents outgoing requests from being sent to the following blacklisted IP address +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). @@ -357,7 +396,7 @@ 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 +Note: The value is ignored when an HTTP proxy is in use. Example configuration: ``` @@ -407,53 +446,53 @@ configuration. Options for each listener include: -`port`: the TCP port to bind to +* `port`: the TCP port to bind to -`bind_addresses`: a list of local addresses to listen on. The default is +* `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: +* `type`: the type of listener. Normally `http`, but other valid options are: -* `manhole`: (see https://matrix-org.github.io/synapse/latest/manhole.html), + * `manhole`: (see https://matrix-org.github.io/synapse/latest/manhole.html), -* `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), + * `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), -* `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). + * `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). * `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. +* `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. Options for each resource are: +* `resources`: Only valid for an 'http' listener. A list of resources to host + on this port. Options for each resource are: -* `names`: a list of names of HTTP resources. See below for a list of valid resource names. + * `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. + * `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. +* `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'. +* `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 https://matrix-org.github.io/synapse/latest/consent_tracking.html. +* `consent`: user consent forms (/_matrix/consent). See https://matrix-org.github.io/synapse/latest/consent_tracking.html. -`federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid` +* `federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid` -`keys`: the key discovery API (/_matrix/keys). +* `keys`: the key discovery API (/_matrix/keys). -`media`: the media API (/_matrix/media). +* `media`: the media API (/_matrix/media). -`metrics`: the metrics interface. See https://matrix-org.github.io/synapse/latest/metrics-howto.html. +* `metrics`: the metrics interface. See https://matrix-org.github.io/synapse/latest/metrics-howto.html. -`openid`: OpenID authentication. +* `openid`: OpenID authentication. -`replication`: the HTTP replication API (/_synapse/replication). See https://matrix-org.github.io/synapse/latest/workers.html. +* `replication`: the HTTP replication API (/_synapse/replication). See https://matrix-org.github.io/synapse/latest/workers.html. -`static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) +* `static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) Example configuration #1: ``` @@ -471,6 +510,7 @@ listeners: ``` Example configuration #2: ``` +listeners: # Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy # that unwraps TLS. # @@ -543,7 +583,7 @@ Useful options for Synapse admins. Config option: `admin_contact` -How to reach the server admin, used in `ResourceLimitError`. +How to reach the server admin, used in `ResourceLimitError`. Defaults to none. Example configuration: ``` @@ -552,13 +592,13 @@ admin_contact: 'mailto:admin@server.com' --- Config option: `hs_disabled` and `hs_disabled_message` -Blocks users from connecting to homeserver and provides a human-readable reason +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: 'Human readable reason for why the HS is blocked' +hs_disabled_message: 'Reason for why the HS is blocked' ``` --- Config option: `limit_usage_by_mau` @@ -576,7 +616,7 @@ 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. +blocking user actions if `limit_usage_by_mau` is enabled. Defaults to 0. Example configuration: ``` @@ -589,7 +629,7 @@ The option `mau_trial_days` is a means to add a grace period for active users. I 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. +session. Defaults to 0. Example configuration: ``` @@ -601,7 +641,7 @@ 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 +interest increasing the mau limit further. Defaults to true, which means that alerting is enabled. Example configuration: @@ -653,7 +693,7 @@ 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. + 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 @@ -809,7 +849,7 @@ The message retention policies feature is disabled by default. Associated options are: * `default_policy`: Default retention policy. If set, Synapse will apply it to rooms that lack the 'm.room.retention' state event. This option is further specified by the - `min_lifetime` and `max_lifetime` options associated with it. Note that the + `min_lifetime` and `max_lifetime` sub-options associated with it. Note that the value of `min_lifetime` doesn't matter much because Synapse doesn't take it into account yet. * `allowed_lifetime_min` and `allowed_lifetime_max`: Retention policy limits. If @@ -873,11 +913,11 @@ Config option: `tls_certificate_path` This option specifies a PEM-encoded X509 certificate for TLS. This certificate, as of Synapse 1.0, will need to be a valid and verifiable -certificate, signed by a recognised Certificate Authority. +certificate, signed by a recognised Certificate Authority. Defaults to none. Be sure to use a `.pem` file that includes the full certificate chain including any intermediate certificates (for instance, if using certbot, use -`fullchain.pem` as your certificate, not `cert.pem`). +`fullchain.pem` as your certificate, not `cert.pem`). Example configuration: ``` @@ -886,7 +926,7 @@ tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" --- Config option: `tls_private_key_path` -PEM-encoded private key for TLS. +PEM-encoded private key for TLS. Defaults to none. Example configuration: ``` @@ -1034,7 +1074,7 @@ A cache 'factor' is a multiplier that can be applied to each of Synapse's caches in order to increase or decrease the maximum number of entries that can be stored. -Caching can be configured through the following options: +Caching can be configured through the following sub-options: * `global_factor`: Controls the global cache factor, which is the default cache factor for all caches if a specific factor for that cache is not otherwise @@ -1095,7 +1135,7 @@ Config option: `database` The `database` setting defines the database that synapse uses to store all of its data. -Associated options: +Associated sub-options: * `name`: this option specifies the database engine to use: either `sqlite3` (for SQLite) or `psycopg2` (for PostgreSQL). If no name is specified Synapse will default to SQLite. @@ -1246,8 +1286,7 @@ rc_admin_redaction: --- Config option: `rc_joins` -This option allows for ratelimiting number of rooms a user can join. It's options -are +This option allows for ratelimiting number of rooms a user can join. Associated sub-options are: * `local`: ratelimits when users are joining rooms the server is already in. Defaults to `per_second: 0.1`, `burst_count: 10`. @@ -1311,7 +1350,9 @@ rc_third_party_invite: --- Config option: `rc_federation` -The rc_federation configuration is made up of the following settings: +Defines limits on federation requests. + +The `rc_federation` configuration has the following sub-options: * `window_size`: window size in milliseconds. Defaults to 1000. * `sleep_limit`: number of federation requests from a single server in a window before the server will delay processing the request. Defaults to 10. @@ -1371,8 +1412,8 @@ media_store_path: "DATADIR/media_store" Config option: `media_storage_providers` Media storage providers allow media to be stored in different -locations. Defaults to none. Associated options are: -* `module`: type of resource, e.g. `file_system`, and associated options: +locations. Defaults to none. Associated sub-options are: +* `module`: type of resource, e.g. `file_system`. Each `module` has the following sub-options: * `store_local`: whether to store newly uploaded local files * `store_remote`: whether to store newly downloaded local files * `store_synchronous`: whether to wait for successful storage for local uploads @@ -1391,7 +1432,7 @@ media_storage_providers: --- Config option: `max_upload_size` -The largest allowed upload size in bytes +The largest allowed upload size in bytes. If you are using a reverse proxy you may also need to set this value in your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default. @@ -1426,7 +1467,7 @@ dynamic_thumbnails: true --- Config option: `thumbnail_sizes` -List of thumbnails to precalculate when an image is uploaded. Associated settings are: +List of thumbnails to precalculate when an image is uploaded. Associated sub-options are: * `width` * `height` * `method`: i.e. `crop`, `scale`, etc. @@ -1509,7 +1550,7 @@ This option sets a list of IP address CIDR ranges that the URL preview spider is to access even if they are specified in `url_preview_ip_range_blacklist`. This is useful for specifying exceptions to wide-ranging blacklisted target IP ranges - e.g. for enabling URL previews for a specific private -website only visible in your network. +website only visible in your network. Defaults to none. Example configuration: ``` @@ -1640,7 +1681,7 @@ recaptcha_private_key: "YOUR_PRIVATE_KEY" --- Config option: `enable_registration_captcha` -Uncomment to enable ReCaptcha checks when registering, preventing signup +Set to true to enable ReCaptcha checks when registering, preventing signup unless a captcha is answered. Requires a valid ReCaptcha public/private key. Defaults to false. @@ -1665,7 +1706,7 @@ Options related to adding a TURN server to Synapse. --- Config option: `turn_uris` -The public URIs of the TURN server to give to clients +The public URIs of the TURN server to give to clients. Example configuration: ``` @@ -1821,7 +1862,7 @@ registrations_require_3pid: Config option: `disable_msisdn_registration` Explicitly disable asking for MSISDNs from the registration -flow (overrides `registrations_require_3pid` if MSISDNs are set as required) +flow (overrides `registrations_require_3pid` if MSISDNs are set as required). Example usage: ``` @@ -1831,7 +1872,7 @@ disable_msisdn_registration: true Config option: `allowed_local_3pids` Mandate that users are only allowed to associate certain formats of -3PIDs with accounts on this server, as specified by the `medium` and `pattern` settings. +3PIDs with accounts on this server, as specified by the `medium` and `pattern` sub-options. Example usage: ``` @@ -1858,7 +1899,7 @@ Config option: `registration_requires_token` Require users to submit a token during registration. Tokens can be managed using the admin API: https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html -Note that `enable_registration` must be set to `true`. +Note that `enable_registration` must be set to true. Disabling this option will not delete any tokens previously generated. Defaults to false. Set to true to enable. From 97a4056f5206cbf3fb0dd65fa10a3b50240464a0 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Sun, 3 Apr 2022 20:34:24 -0700 Subject: [PATCH 05/11] more fixes --- docs/usage/configuration/config_documentation.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index b4bd50ec397f..a5a922e474a6 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -2234,7 +2234,7 @@ receive invites to the room: - m.room.create - m.room.topic -To change the default behavior, use the following options: +To change the default behavior, use the following sub-options: * `disable_default_event_types`: set to true to disable the above defaults. If this is enabled, only the event types listed in `additional_event_types` are shared. Defaults to false. @@ -2439,11 +2439,13 @@ to find a full list options for configuring pysaml, read the docs [here](https:/ 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 option `config_path`. +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: + * `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 options for configuring pysaml: + 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. From 9c4598ac61fc5fbe5ce3f09e1922d7450d1ff0d4 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Sun, 3 Apr 2022 20:40:19 -0700 Subject: [PATCH 06/11] fix index link --- docs/usage/configuration/config_documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index a5a922e474a6..04dcb4db72f9 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -72,7 +72,7 @@ apply if you want your config file to be read properly. A few helpful things to [Server](#server) -[Homeserver Blocking](#homserver-blocking) +[Homeserver Blocking](#homeserver-blocking) [TLS](#tls) From ed69d52c152c944f6c00db529f54167a0db9f763 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Mon, 4 Apr 2022 11:42:31 -0700 Subject: [PATCH 07/11] fix links --- .../configuration/config_documentation.md | 158 +++++++++--------- 1 file changed, 80 insertions(+), 78 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 04dcb4db72f9..1738d9353b67 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -4,7 +4,9 @@ This is intended as a guide to the synapse configuration. The behavior of a Syna 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 behavior 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. +thinking about options, the config as generated sets sensible defaults for all values. Do note however that the +database defualts to SQLite, which is not recommended for production usage. You can read more on this subject +[here](../../setup/installation.md#using-postgresql). ## Config Conventions @@ -120,7 +122,7 @@ apply if you want your config file to be read properly. A few helpful things to Server admins can expand Synapse's functionality with external modules. -See https://matrix-org.github.io/synapse/latest/modules/index.html for more +See [here](../../modules/index.md) for more documentation on how to configure or create custom modules for Synapse. @@ -159,7 +161,7 @@ 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 https://matrix-org.github.io/synapse/latest/delegate.html +See [here](../../delegate.md) for information on how to host Synapse on a subdomain while preserving a clean `server_name`. @@ -245,7 +247,7 @@ 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` flag below `presence` to false to +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. @@ -354,7 +356,7 @@ 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. -1 means no upper limit. +and sync operations. Defaults to 100. A value of -1 means no upper limit. Example configuration: @@ -444,20 +446,20 @@ Config option: `listeners` List of ports that Synapse should listen on, their purpose and their configuration. -Options for each listener include: +Sub-options for each listener include: -* `port`: the TCP port to bind to +* `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 https://matrix-org.github.io/synapse/latest/manhole.html), + * `manhole`: (see the docs [here](../../manhole.md)), - * `metrics`: (see https://matrix-org.github.io/synapse/latest/metrics-howto.html), + * `metrics`: (see the docs [here](../../metrics-howto.md)), - * `replication`: (see https://matrix-org.github.io/synapse/latest/workers.html). + * `replication`: (see the docs [here](../../workers.md)). * `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. @@ -465,7 +467,7 @@ Options for each listener include: behind a reverse-proxy. * `resources`: Only valid for an 'http' listener. A list of resources to host - on this port. Options for each resource are: + 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. @@ -478,7 +480,7 @@ 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 https://matrix-org.github.io/synapse/latest/consent_tracking.html. +* `consent`: user consent forms (/_matrix/consent). See [here](../../consent_tracking.md) for more. * `federation`: the server-server API (/_matrix/federation). Also implies `media`, `keys`, `openid` @@ -486,11 +488,11 @@ Valid resource names are: * `media`: the media API (/_matrix/media). -* `metrics`: the metrics interface. See https://matrix-org.github.io/synapse/latest/metrics-howto.html. +* `metrics`: the metrics interface. See [here](../../metrics-howto.md). -* `openid`: OpenID authentication. +* `openid`: OpenID authentication. See [here](../../openid.md). -* `replication`: the HTTP replication API (/_synapse/replication). See https://matrix-org.github.io/synapse/latest/workers.html. +* `replication`: the HTTP replication API (/_synapse/replication). See [here](../../workers.md). * `static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) @@ -543,7 +545,7 @@ listeners: Config option: `manhole_settings` Connection settings for the manhole. You can find more information -on the manhole [here](../../manhole.md). Manhole settings include: +on the manhole [here](../../manhole.md). 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. @@ -821,7 +823,7 @@ find template files in to use to generate email or HTML page contents. If not set, or a file is not found within the template directory, a default template from within the Synapse package will be used. -See https://matrix-org.github.io/synapse/latest/templates.html for more +See [here](../../templates.md) for more information about using custom templates. Example configuration: @@ -846,7 +848,7 @@ purged are ignored and not stored again. The message retention policies feature is disabled by default. -Associated options are: +This setting has the following sub-options: * `default_policy`: Default retention policy. If set, Synapse will apply it to rooms that lack the 'm.room.retention' state event. This option is further specified by the `min_lifetime` and `max_lifetime` sub-options associated with it. Note that the @@ -857,7 +859,7 @@ Associated options are: which contains a `min_lifetime` or a `max_lifetime` that's out of these bounds, Synapse will cap the room's policy to these limits when running purge jobs. -* `purge_jobs` and the associated `shortest_max_lifetime` and `longest_max_lifetime`: +* `purge_jobs` and the associated `shortest_max_lifetime` and `longest_max_lifetime` sub-options: Server admins can define the settings of the background jobs purging the events whose lifetime has expired under the `purge_jobs` section. @@ -1061,7 +1063,7 @@ Options related to caching Config option: `event_cache_size` The number of events to cache in memory. Not affected by -`caches.global_factor`. Defaults to 10K +`caches.global_factor`. Defaults to 10K. Example configuration: ``` @@ -1146,18 +1148,17 @@ Associated sub-options: * `allow_unsafe_locale` is an option specific to Postgres. Under the default behavior, Synapse will refuse to start if the postgres db is set to a non-C locale. You can override this behavior (which is *not* recommended) by setting `allow_unsafe_locale` to true. Note that doing so may corrupt your database. You can find more information - here: https://matrix-org.github.io/synapse/latest/postgres.html#fixing-incorrect-collate-or-ctype and here: - https://wiki.postgresql.org/wiki/Locale_data_changes + [here](../../postgres.md#fixing-incorrect-collate-or-ctype) and [here](https://wiki.postgresql.org/wiki/Locale_data_changes). * `args` gives options which are passed through to the database engine, except for options starting with `cp_`, which are used to configure the Twisted connection pool. For a reference to valid arguments, see: - * for sqlite: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect - * for postgres: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS - * for the connection pool: https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__ + * for [sqlite](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect) + * for [postgres](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS) + * for [the connection pool](https://twistedmatrix.com/documents/current/api/twisted.enterprise.adbapi.ConnectionPool.html#__init__) For more information on using Synapse with Postgres, -see https://matrix-org.github.io/synapse/latest/postgres.html. +see [here](../../postgres.md). Example SQLite configuration: ``` @@ -1188,8 +1189,7 @@ Config options related to logging. --- Config option: `log_config` -This option specifies a yaml python logging config file as described by -https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema +This option specifies a yaml python logging config file as described [here](https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema). Example configuration: ``` @@ -1286,7 +1286,7 @@ rc_admin_redaction: --- Config option: `rc_joins` -This option allows for ratelimiting number of rooms a user can join. Associated sub-options are: +This option allows for ratelimiting number of rooms a user can join. This setting has the following sub-options: * `local`: ratelimits when users are joining rooms the server is already in. Defaults to `per_second: 0.1`, `burst_count: 10`. @@ -1413,11 +1413,11 @@ Config option: `media_storage_providers` Media storage providers allow media to be stored in different locations. Defaults to none. Associated sub-options are: -* `module`: type of resource, e.g. `file_system`. Each `module` has the following sub-options: - * `store_local`: whether to store newly uploaded local files - * `store_remote`: whether to store newly downloaded local files - * `store_synchronous`: whether to wait for successful storage for local uploads - * `config`: sets a path to the resource through the `directory` option +* `module`: type of resource, e.g. `file_system`. +* `store_local`: whether to store newly uploaded local files +* `store_remote`: whether to store newly downloaded local files +* `store_synchronous`: whether to wait for successful storage for local uploads +* `config`: sets a path to the resource through the `directory` option Example configuration: ``` @@ -1436,7 +1436,7 @@ The largest allowed upload size in bytes. If you are using a reverse proxy you may also need to set this value in your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body size by default. -See https://matrix-org.github.io/synapse/latest/reverse_proxy.html. +See [here](../../reverse_proxy.md) for more on using a reverse proxy with Synapse. Example configuration: ``` @@ -1568,8 +1568,8 @@ This is more useful if you know there is an entire shape of URL that you know that will never want synapse to try to spider. Each list entry is a dictionary of url component attributes as returned -by urlparse.urlsplit as applied to the absolute form of the URL. See -https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit for more +by urlparse.urlsplit as applied to the absolute form of the URL. See +[here](https://docs.python.org/2/library/urlparse.html#urlparse.urlsplit) for more information. Some examples are: * `username` @@ -1656,7 +1656,7 @@ oembed: --- ## Captcha ## -See docs/CAPTCHA_SETUP.md for full details of configuring captcha. +See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha. --- Config option: `recaptcha_public_key` @@ -1897,8 +1897,7 @@ enable_3pid_lookup: false Config option: `registration_requires_token` Require users to submit a token during registration. -Tokens can be managed using the admin API: -https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html +Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md). Note that `enable_registration` must be set to true. Disabling this option will not delete any tokens previously generated. Defaults to false. Set to true to enable. @@ -1974,8 +1973,7 @@ identifier type, set the value to the URL of that identity server as shown in th examples below. Servers handling the these requests must answer the `/requestToken` endpoints defined -by the Matrix Identity Service API specification: -https://matrix.org/docs/spec/identity_service/latest +by the Matrix Identity Service API [specification](https://matrix.org/docs/spec/identity_service/latest). Example usage: ``` @@ -2048,7 +2046,7 @@ homeserver registers. By default the auto-created rooms are publicly joinable from any federated server. Use the `autocreate_auto_join_rooms_federated` and -`autocreate_auto_join_room_preset` settings below to customise this behaviour. +`autocreate_auto_join_room_preset` settings to customise this behaviour. Setting to false means that if the rooms are not manually created, users cannot be auto-joined since they do not exist. @@ -2372,7 +2370,7 @@ warning on start-up. To suppress this warning, set `suppress_key_server_warning` to true. Options for each entry in the list include: -* `server_name`: the name of the server. required. +* `server_name`: the name of the server. Required. * `verify_keys`: an optional map from key id to base64-encoded public key. If specified, we will check that the response is signed by at least one of the given keys. @@ -2391,7 +2389,7 @@ trusted_key_servers: "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr" - server_name: "my_other_trusted_server.example.com" ``` -Example usage #1: +Example usage #2: ``` trusted_key_servers: - server_name: "matrix.org" @@ -2426,8 +2424,8 @@ 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 - * password_config.enabled + * `enable_registration` + * `password_config.enabled` You will also want to investigate the settings under the "sso" configuration section below. @@ -2572,13 +2570,13 @@ saml2_config: Config option: `oidc_providers` List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration -and login. See https://matrix-org.github.io/synapse/latest/openid.html +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 +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: @@ -2760,7 +2758,7 @@ oidc_providers: Config option: `cas_config` Enable Central Authentication Service (CAS) for registration and login. -Has the following options: +Has the following sub-options: * `enabled`: Set this to true to enable authorization against a CAS server. Defaults to false. * `server_url`: The URL of the CAS authorization endpoint. @@ -2788,8 +2786,8 @@ Config option: `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 -https://matrix-org.github.io/synapse/latest/templates.html for more information. +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 @@ -2835,9 +2833,9 @@ 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 https://matrix-org.github.io/synapse/latest/jwt.html. +See [here](../../jwt.md) for more. -Additional options for this setting include: +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 @@ -2867,10 +2865,13 @@ jwt_config: --- Config option: `password_config` +Use this setting to enable password-based logins. + +This setting has the following sub-options: * `enabled`: Defaults to true. * `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. + if you have other `password_providers`. Defaults to true. * `pepper`: Set the value here to a secret random string for extra security. # Uncomment and change 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. @@ -2930,9 +2931,9 @@ Config option: `email` Configuration for sending emails from Synapse. Server admins can configure custom templates for email content. See -https://matrix-org.github.io/synapse/latest/templates.html for more information. +[here](../../templates.md) for more information. -This option has the following subsections: +This setting has the following sub-options: * `smtp_host`: The hostname of the outgoing SMTP server to use. Defaults to 'localhost'. * `smtp_port`: The port on the mail server for outgoing SMTP. Defaults to 25. * `smtp_user` and `smtp_pass`: Username/password for authentication to the SMTP server. By default, no @@ -3030,7 +3031,9 @@ Configuration settings related to push notifications --- Config option: `push` -This option has a number of sub-options relating to push notifications. They are as follows: +This setting defines options for push notifications. + +This option has a number of sub-options. They are as follows: * `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`). @@ -3041,9 +3044,7 @@ This option has a number of sub-options relating to push notifications. They are 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. - # TODO: is this still correct? - Defaults to true. to include message details. Set to false to only - include the event ID and room ID in push notification payloads. + 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 @@ -3068,10 +3069,10 @@ 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` +* "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 +* "off": this option will take no effect The default value is "off". @@ -3096,7 +3097,7 @@ Config option: `group_creation_prefix` If enabled/present, non-server admins can only create groups with local parts starting with this prefix. -# todo: can I rip out this group setting? + Example usage: ``` group_creation_prefix: "unofficial_" @@ -3104,6 +3105,8 @@ group_creation_prefix: "unofficial_" --- Config option: `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. @@ -3133,8 +3136,7 @@ user_directory: --- Config option: `user_consent` -For detailed instructions on user consent configuration, see -https://matrix-org.github.io/synapse/latest/consent_tracking.html +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`, in particular `template_dir` and `version`. # TODO: link `listeners` @@ -3185,8 +3187,8 @@ user_consent: --- Config option: `stats` -Settings for local room and user statistics collection. See -https://matrix-org.github.io/synapse/latest/room_and_user_statistics.html. +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 @@ -3208,7 +3210,7 @@ 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. -Other options for this setting include: +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 @@ -3305,10 +3307,10 @@ including requests, key lookups etc., across any server running synapse or any other services which support opentracing (specifically those implemented with Jaeger). -Options include: +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 https://matrix-org.github.io/synapse/latest/opentracing.html. + 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, @@ -3316,7 +3318,7 @@ Options include: 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/. + mostly related to trace sampling which is documented [here](https://www.jaegertracing.io/docs/latest/sampling/). Example usage: ``` @@ -3415,9 +3417,9 @@ worker_replication_secret: "secret_secret" ``` Config option: `redis` -Configuration for [Redis]() # TODO add link when using workers. This *must* be enabled when +Configuration for Redis when using workers. This *must* be enabled when using workers (unless using old style direct TCP configuration). -Has the following options: +This setting has the following sub-options: * `enabled`: whether to use Redis support. Defaults to false. * `host` and `port`: Optional host and port to use to connect to redis. Defaults to localhost and 6379 @@ -3440,7 +3442,7 @@ Config option: `background_updates` Background updates are database updates that are run in the background in batches. The duration, minimum batch size, default batch size, whether to sleep between batches and if so, how long to sleep can all be configured. This is helpful to speed up or slow down the updates. -Options are: +This setting has the following sub-options: * `background_update_duration_ms`: How long in milliseconds to run a batch of background updates for. Defaults to 100. Set a different time to change the default. * `sleep_enabled`: Whether to sleep between updates. Defaults to true. Set to false to change the default. From d08787ba31ed633578267346b3de9e6edba0e4ba Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Mon, 4 Apr 2022 11:56:05 -0700 Subject: [PATCH 08/11] newfragment --- changelog.d/12368.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/12368.doc diff --git a/changelog.d/12368.doc b/changelog.d/12368.doc new file mode 100644 index 000000000000..62e4cb2c7ef5 --- /dev/null +++ b/changelog.d/12368.doc @@ -0,0 +1 @@ +Add a manual documenting config file options. \ No newline at end of file From a67d32025d3ec4a3ff13e7fe21ae0d408c556500 Mon Sep 17 00:00:00 2001 From: Shay Date: Wed, 6 Apr 2022 12:18:27 -0700 Subject: [PATCH 09/11] Update docs/usage/configuration/config_documentation.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../usage/configuration/config_documentation.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 1738d9353b67..bec24c9eb7dc 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -13,17 +13,12 @@ database defualts to SQLite, which is not recommended for production usage. You 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 +* `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. From 399ac15b89d91c80878284939540f36b1604f389 Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Wed, 6 Apr 2022 12:20:29 -0700 Subject: [PATCH 10/11] apply some suggestions --- docs/SUMMARY.md | 1 + docs/usage/configuration/config_documentation.md | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 21f80efc9998..a06a2fe8d6a9 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -17,6 +17,7 @@ # Usage - [Federation](federate.md) - [Configuration](usage/configuration/README.md) + - [Configuration Manual](usage/configuration/config_documentation.md) - [Homeserver Sample Config File](usage/configuration/homeserver_sample_config.md) - [Logging Sample Config File](usage/configuration/logging_sample_config.md) - [Structured Logging](structured_logging.md) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index 1738d9353b67..7649a8d27b74 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -1,11 +1,11 @@ -## Welcome +## 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 behavior the setting governs. +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 defualts to SQLite, which is not recommended for production usage. You can read more on this subject +database defaults to SQLite, which is not recommended for production usage. You can read more on this subject [here](../../setup/installation.md#using-postgresql). ## Config Conventions From 365be5c3e46942bd83b6a5f8f190658bc1ac109f Mon Sep 17 00:00:00 2001 From: "H. Shay" Date: Wed, 6 Apr 2022 14:46:01 -0700 Subject: [PATCH 11/11] requested changes --- .../configuration/config_documentation.md | 525 ++++++++---------- 1 file changed, 239 insertions(+), 286 deletions(-) diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md index cd43cb548c07..9c864af6ec32 100644 --- a/docs/usage/configuration/config_documentation.md +++ b/docs/usage/configuration/config_documentation.md @@ -1,4 +1,4 @@ -## Configuring Synapse +# 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, @@ -23,7 +23,7 @@ followed by a letter. Letters have the following meanings: For example, setting `redaction_retention_period: 5m` would remove redacted messages from the database after 5 minutes, rather than 5 months. -## Yaml +### YAML The configuration file is a [YAML](https://yaml.org/) 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 @@ -31,11 +31,11 @@ apply if you want your config file to be read properly. A few helpful things to applied, but in example #2 the setting will not be read and a default will be applied. Example #1: - ``` + ```yaml pid_file: DATADIR/homeserver.pid ``` Example #2: - ``` + ```yaml #pid_file: DATADIR/homeserver.pid ``` * Indentation matters! The indentation before a setting @@ -49,12 +49,12 @@ apply if you want your config file to be read properly. A few helpful things to is an option that Synapse doesn't recognize and thus ignores. Example #1: - ``` + ```yaml presence: enabled: false ``` Example #2: - ``` + ```yaml presence: enabled: false ``` @@ -64,56 +64,8 @@ apply if you want your config file to be read properly. A few helpful things to In addition, each setting has an example of its usage, with the proper indentation shown. -## Index -[Modules](#modules) - -[Server](#server) - -[Homeserver Blocking](#homeserver-blocking) - -[TLS](#tls) - -[Federation](#federation) -[Caching](#caching) - -[Database](#database) - -[Logging](#logging) - -[Ratelimiting](#ratelimiting) - -[Media Store](#media-store) - -[Captcha](#captcha) - -[Turn](#turn) - -[Registration](#registration) - -[Metrics](#metrics) - -[API Configuration](#api-configuration) - -[Signing Keys](#signing-keys) - -[Single Sign On Integration](#single-sign-on-integration) - -[Push](#push) - -[Rooms](#rooms) - -[Opentracing](#opentracing) - -[Workers](#workers) - -[Background Updates](#background-updates) - - - - - -## Modules ## +## Modules Server admins can expand Synapse's functionality with external modules. @@ -131,7 +83,7 @@ for the `module`. Defaults to none. Example configuration: -``` +```yaml modules: - module: my_super_module.MySuperClass config: @@ -167,11 +119,11 @@ lowercase and may contain an explicit port. There is no default for this option. Example configuration #1: -``` +```yaml server_name: matrix.org ``` Example configuration #2: -``` +```yaml server_name: localhost:8080 ``` --- @@ -180,7 +132,7 @@ Config option: `pid_file` When running Synapse as a daemon, the file to store the pid in. Defaults to none. Example configuration: -``` +```yaml pid_file: DATADIR/homeserver.pid ``` --- @@ -189,7 +141,7 @@ Config option: `web_client_location` The absolute URL to the web client which `/` will redirect to. Defaults to none. Example configuration: -``` +```yaml web_client_location: https://riot.example.com/ ``` --- @@ -205,7 +157,7 @@ Otherwise, it should be the URL to reach Synapse's client HTTP listener (see Defaults to `https:///`. Example configuration: -``` +```yaml public_baseurl: https://example.com/ ``` --- @@ -224,7 +176,7 @@ See https://matrix-org.github.io/synapse/latest/delegate.html for more information. Example configuration: -``` +```yaml serve_server_wellknown: true ``` --- @@ -235,7 +187,7 @@ Zero is used to indicate synapse should set the soft limit to the hard limit. Defaults to 0. Example configuration: -``` +```yaml soft_file_limit: 3 ``` --- @@ -247,7 +199,7 @@ disable presence tracking on this homeserver. Defaults to true. This option replaces the previous top-level 'use_presence' option. Example configuration: -``` +```yaml presence: enabled: false ``` @@ -259,7 +211,7 @@ users through the client API. Defaults to false. Note that profile data is also via the federation API, unless `allow_profile_lookup_over_federation` is set to false. Example configuration: -``` +```yaml require_auth_for_profile_requests: true ``` --- @@ -271,7 +223,7 @@ requests. Profile requests from other servers should be checked by the requesting server. Defaults to false. Example configuration: -``` +```yaml limit_profile_requests_to_users_who_share_rooms: true ``` --- @@ -284,7 +236,7 @@ of the above two settings, and whether or not the users share a server. Defaults to true. Example configuration: -``` +```yaml include_profile_data_on_invite: false ``` --- @@ -295,7 +247,7 @@ public rooms directory through the client API, meaning that anyone can query the room directory. Defaults to false. Example configuration: -``` +```yaml allow_public_rooms_without_auth: true ``` --- @@ -305,7 +257,7 @@ If set to true, allows any other homeserver to fetch the server's public rooms directory via federation. Defaults to false. Example configuration: -``` +```yaml allow_public_rooms_over_federation: true ``` --- @@ -321,7 +273,7 @@ to "1". Currently defaults to "9". Example configuration: -``` +```yaml default_room_version: "8" ``` --- @@ -331,7 +283,7 @@ The garbage collection threshold parameters to pass to `gc.set_threshold`, if de Defaults to none. Example configuration: -``` +```yaml gc_thresholds: [700, 10, 10] ``` --- @@ -344,7 +296,7 @@ indicates that a second must pass between consecutive generation 0 GCs, etc. Defaults to `[1s, 10s, 30s]`. Example configuration: -``` +```yaml gc_min_interval: [0.5s, 30s, 1m] ``` --- @@ -355,7 +307,7 @@ and sync operations. Defaults to 100. A value of -1 means no upper limit. Example configuration: -``` +```yaml filter_timeline_limit: 5000 ``` --- @@ -365,7 +317,7 @@ Whether room invites to users on this server should be blocked (except those sent by local server admins). Defaults to false. Example configuration: -``` +```yaml block_non_admin_invites: true ``` --- @@ -375,7 +327,7 @@ 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: -``` +```yaml enable_search: false ``` --- @@ -396,7 +348,7 @@ 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: -``` +```yaml ip_range_blacklist: - '127.0.0.0/8' - '10.0.0.0/8' @@ -431,7 +383,7 @@ This whitelist overrides `ip_range_blacklist` and defaults to an empty list. Example configuration: -``` +```yaml ip_range_whitelist: - '192.168.1.1' ``` @@ -492,7 +444,7 @@ Valid resource names are: * `static`: static resources under synapse/static (/_matrix/static). (Mostly useful for 'fallback authentication'.) Example configuration #1: -``` +```yaml listeners: # TLS-enabled listener: for when matrix traffic is sent directly to synapse. # @@ -506,7 +458,7 @@ listeners: - names: [client, federation] ``` Example configuration #2: -``` +```yaml listeners: # Unsecure HTTP listener: for when matrix traffic passes through a reverse proxy # that unwraps TLS. @@ -548,7 +500,7 @@ on the manhole [here](../../manhole.md). Manhole sub-options include: which could allow traffic to be intercepted if sent over a public network. Example configuration: -``` +```yaml manhole_settings: username: manhole password: mypassword @@ -569,7 +521,7 @@ This setting defines the threshold (i.e. number of forward extremities in the ro The default value is 10. Example configuration: -``` +```yaml dummy_events_threshold: 5 ``` --- @@ -583,7 +535,7 @@ Config option: `admin_contact` How to reach the server admin, used in `ResourceLimitError`. Defaults to none. Example configuration: -``` +```yaml admin_contact: 'mailto:admin@server.com' ``` --- @@ -593,7 +545,7 @@ Blocks users from connecting to the homeserver and provides a human-readable rea why the connection was blocked. Defaults to false. Example configuration: -``` +```yaml hs_disabled: true hs_disabled_message: 'Reason for why the HS is blocked' ``` @@ -606,7 +558,7 @@ reached the server returns a `ResourceLimitError` with error type `Codes.RESOURC Defaults to false. If this is enabled, a value for `max_mau_value` must also be set. Example configuration: -``` +```yaml limit_usage_by_mau: true ``` --- @@ -616,7 +568,7 @@ This option sets the hard limit of monthly active users above which the server w blocking user actions if `limit_usage_by_mau` is enabled. Defaults to 0. Example configuration: -``` +```yaml max_mau_value: 50 ``` --- @@ -629,7 +581,7 @@ sign up in a short space of time never to return after their initial session. Defaults to 0. Example configuration: -``` +```yaml mau_trial_days: 5 ``` --- @@ -642,7 +594,7 @@ interest increasing the mau limit further. Defaults to true, which means that alerting is enabled. Example configuration: -``` +```yaml mau_limit_alerting: false ``` --- @@ -653,7 +605,7 @@ be populated, however no one will be limited based on these numbers. If `limit_u is true, this is implied to be true. Defaults to false. Example configuration: -``` +```yaml mau_stats_only: true ``` --- @@ -665,7 +617,7 @@ Defaults to none. Add accounts by specifying the `medium` and `address` of the reserved threepid (3rd party identifier). Example configuration: -``` +```yaml mau_limit_reserved_threepids: - medium: 'email' address: 'reserved_user@example.com' @@ -677,7 +629,7 @@ This option is used by phonehome stats to group together related servers. Defaults to none. Example configuration: -``` +```yaml server_context: context ``` --- @@ -697,7 +649,7 @@ Room complexity is an arbitrary measure based on factors such as the number of users in the room. Example configuration: -``` +```yaml limit_remote_rooms: enabled: true complexity: 0.5 @@ -711,7 +663,7 @@ Whether to require a user to be in the room to add an alias to it. Defaults to true. Example configuration: -``` +```yaml require_membership_for_aliases: false ``` --- @@ -722,7 +674,7 @@ events with profile information that differs from the target's global profile. Defaults to true. Example configuration: -``` +```yaml allow_per_room_profiles: false ``` --- @@ -734,7 +686,7 @@ Use M for MB and K for KB. Note that user avatar changes will not work if this is set without using Synapse's media repository. Example configuration: -``` +```yaml max_avatar_size: 10M ``` --- @@ -746,7 +698,7 @@ Note that user avatar changes will not work if this is set without using Synapse's media repository. Example configuration: -``` +```yaml allowed_avatar_mimetypes: ["image/png", "image/jpeg", "image/gif"] ``` --- @@ -758,7 +710,7 @@ this period redacted events get replaced with their redacted form in the DB. Defaults to `7d`. Set to `null` to disable. Example configuration: -``` +```yaml redaction_retention_period: 28d ``` --- @@ -769,7 +721,7 @@ How long to track users' last seen time and IPs in the database. Defaults to `28d`. Set to `null` to disable clearing out of old rows. Example configuration: -``` +```yaml user_ips_max_age: 14d ``` --- @@ -784,7 +736,7 @@ If this option is enabled, instead of returning an error, these endpoints will act as if no error happened and return a fake session ID ('sid') to clients. Example configuration: -``` +```yaml request_token_inhibit_3pid_errors: true ``` --- @@ -806,7 +758,7 @@ allowed. Setting this value to an empty list will instead disallow all domains. Example configuration: -``` +```yaml next_link_domain_whitelist: ["matrix.org"] ``` --- @@ -822,7 +774,7 @@ See [here](../../templates.md) for more information about using custom templates. Example configuration: -``` +```yaml templates: custom_template_directory: /path/to/custom/templates/ ``` @@ -886,7 +838,7 @@ This setting has the following sub-options: configuration). Example configuration: -``` +```yaml retention: enabled: true default_policy: @@ -903,7 +855,7 @@ retention: --- ## TLS ## -Options relating to TLS +Options related to TLS. --- Config option: `tls_certificate_path` @@ -917,7 +869,7 @@ any intermediate certificates (for instance, if using certbot, use `fullchain.pem` as your certificate, not `cert.pem`). Example configuration: -``` +```yaml tls_certificate_path: "CONFDIR/SERVERNAME.tls.crt" ``` --- @@ -926,7 +878,7 @@ Config option: `tls_private_key_path` PEM-encoded private key for TLS. Defaults to none. Example configuration: -``` +```yaml tls_private_key_path: "CONFDIR/SERVERNAME.tls.key" ``` --- @@ -936,7 +888,7 @@ Whether to verify TLS server certificates for outbound federation requests. Defaults to true. To disable certificate verification, set the option to false. Example configuration: -``` +```yaml federation_verify_certificates: false ``` --- @@ -950,7 +902,7 @@ of the public Matrix network: only configure it to `1.3` if you have an entirely private federation setup and you can ensure TLS 1.3 support. Example configuration: -``` +```yaml federation_client_minimum_tls_version: 1.2 ``` --- @@ -966,7 +918,7 @@ of homeservers, you likely want to use a private CA instead. Only effective if `federation_verify_certicates` is `true`. Example configuration: -``` +```yaml federation_certificate_verification_whitelist: - lon.example.com - "*.domain.com" @@ -984,7 +936,7 @@ Note that this list will replace those that are provided by your operating environment. Certificates must be in PEM format. Example configuration: -``` +```yaml federation_custom_ca_list: - myCA1.pem - myCA2.pem @@ -1005,7 +957,7 @@ purely on this application-layer restriction. If not specified, the default is to whitelist everything. Example configuration: -``` +```yaml federation_domain_whitelist: - lon.example.com - nyc.example.com @@ -1022,7 +974,7 @@ at either end or with the intermediate network. By default, no domains are monitored in this way. Example configuration: -``` +```yaml federation_metrics_domains: - matrix.org - example.com @@ -1035,7 +987,7 @@ Federation API allows other homeservers to obtain profile data of any user on this homeserver. Example configuration: -``` +```yaml allow_profile_lookup_over_federation: false ``` --- @@ -1046,7 +998,7 @@ Federation API allows other homeservers to obtain device display names of any us on this homeserver. Example configuration: -``` +```yaml allow_device_name_lookup_over_federation: false ``` --- @@ -1061,7 +1013,7 @@ The number of events to cache in memory. Not affected by `caches.global_factor`. Defaults to 10K. Example configuration: -``` +```yaml event_cache_size: 15K ``` --- @@ -1114,7 +1066,7 @@ Caching can be configured through the following sub-options: Example configuration: -``` +```yaml caches: global_factor: 1.0 per_cache_factors: @@ -1187,7 +1139,7 @@ Config option: `log_config` This option specifies a yaml python logging config file as described [here](https://docs.python.org/3.7/library/logging.config.html#configuration-dictionary-schema). Example configuration: -``` +```yaml log_config: "CONFDIR/SERVERNAME.log.config" ``` --- @@ -1207,7 +1159,7 @@ This is a ratelimiting option for messages that ratelimits sending based on the is using. It defaults to: `per_second: 0.2`, `burst_count: 10`. Example configuration: -``` +```yaml rc_message: per_second: 0.5 burst_count: 15 @@ -1219,7 +1171,7 @@ This option ratelimits registration requests based on the client's IP address. It defaults to `per_second: 0.17`, `burst_count: 3`. Example configuration: -``` +```yaml rc_registration: per_second: 0.15 burst_count: 2 @@ -1232,7 +1184,7 @@ the client's IP address. Defaults to `per_second: 0.1`, `burst_count: 5`. Example configuration: -``` +```yaml rc_registration_token_validity: per_second: 0.3 burst_count: 6 @@ -1253,7 +1205,7 @@ This option specifies several limits for login: attempts for this account. Defaults to `per_second: 0.17`, `burst_count: 3`. Example configuration: -``` +```yaml rc_login: address: per_second: 0.15 @@ -1273,7 +1225,7 @@ set then it uses the same ratelimiting as per `rc_message`. This is useful to allow room admins to deal with abuse quickly. Example configuration: -``` +```yaml rc_admin_redaction: per_second: 1 burst_count: 50 @@ -1291,7 +1243,7 @@ This option allows for ratelimiting number of rooms a user can join. This settin `per_second: 0.01`, `burst_count: 10` Example configuration: -``` +```yaml rc_joins: local: per_second: 0.2 @@ -1307,7 +1259,7 @@ This option ratelimits how often a user or IP can attempt to validate a 3PID. Defaults to `per_second: 0.003`, `burst_count: 5`. Example configuration: -``` +```yaml rc_3pid_validation: per_second: 0.003 burst_count: 5 @@ -1320,7 +1272,7 @@ specific user. `per_room` defaults to `per_second: 0.3`, `burst_count: 10` and `per_user` defaults to `per_second: 0.003`, `burst_count: 5`. Example configuration: -``` +```yaml rc_invites: per_room: per_second: 0.5 @@ -1337,7 +1289,7 @@ such as an email address or a phone number) based on the account that's sending the invite. Defaults to `per_second: 0.2`, `burst_count: 10`. Example configuration: -``` +```yaml rc_third_party_invite: per_second: 0.2 burst_count: 10 @@ -1359,7 +1311,7 @@ The `rc_federation` configuration has the following sub-options: from a single server. Defaults to 3. Example configuration: -``` +```yaml rc_federation: window_size: 750 sleep_limit: 15 @@ -1377,7 +1329,7 @@ If we end up trying to send out more read-receipts, they will get buffered up into fewer transactions. Defaults to 50. Example configuration: -``` +```yaml federation_rr_transactions_per_room_per_second: 40 ``` --- @@ -1391,7 +1343,7 @@ Enable the media store service in the Synapse master. Defaults to true. Set to false if you are using a separate media store worker. Example configuration: -``` +```yaml enable_media_repo: false ``` --- @@ -1400,7 +1352,7 @@ Config option: `media_store_path` Directory where uploaded images and attachments are stored. Example configuration: -``` +```yaml media_store_path: "DATADIR/media_store" ``` --- @@ -1415,7 +1367,7 @@ locations. Defaults to none. Associated sub-options are: * `config`: sets a path to the resource through the `directory` option Example configuration: -``` +```yaml media_storage_providers: - module: file_system store_local: false @@ -1434,7 +1386,7 @@ your reverse proxy's config. Defaults to 50M. Notably Nginx has a small max body See [here](../../reverse_proxy.md) for more on using a reverse proxy with Synapse. Example configuration: -``` +```yaml max_upload_size: 60M ``` --- @@ -1443,7 +1395,7 @@ Config option: `max_image_pixels` Maximum number of pixels that will be thumbnailed. Defaults to 32M. Example configuration: -``` +```yaml max_image_pixels: 35M ``` --- @@ -1456,7 +1408,7 @@ generate a new thumbnail. If false the server will pick a thumbnail from a precalculated list. Defaults to false. Example configuration: -``` +```yaml dynamic_thumbnails: true ``` --- @@ -1468,7 +1420,7 @@ List of thumbnails to precalculate when an image is uploaded. Associated sub-opt * `method`: i.e. `crop`, `scale`, etc. Example configuration: -``` +```yaml thumbnail_sizes: - width: 32 height: 32 @@ -1493,7 +1445,7 @@ It is disabled by default. Set to true to enable. If enabled you must specify a `url_preview_ip_range_blacklist` blacklist. Example configuration: -``` +```yaml url_preview_enabled: true ``` --- @@ -1516,7 +1468,7 @@ you use the following example list as a starting point. Note: The value is ignored when an HTTP proxy is in use. Example configuration: -``` +```yaml url_preview_ip_range_blacklist: - '127.0.0.0/8' - '10.0.0.0/8' @@ -1548,7 +1500,7 @@ target IP ranges - e.g. for enabling URL previews for a specific private website only visible in your network. Defaults to none. Example configuration: -``` +```yaml url_preview_ip_range_whitelist: - '192.168.1.1' ``` @@ -1579,7 +1531,7 @@ specified component matches for a given list item succeed, the URL is blacklisted. Example configuration: -``` +```yaml url_preview_url_blacklist: # blacklist any URL with a username in its URI - username: '*' @@ -1604,7 +1556,7 @@ Config option: `max_spider_size` The largest allowed URL preview spidering size in bytes. Defaults to 10M. Example configuration: -``` +```yaml max_spider_size: 8M ``` --- @@ -1625,7 +1577,7 @@ using quality value syntax (;q=). '*' translates to any language. Defaults to "en". Example configuration: -``` +```yaml url_preview_accept_language: - en-UK - en-US;q=0.9 @@ -1642,7 +1594,7 @@ these default oEmbed URLs. Use `additional_providers` to specify additional file should be in the form of providers.json). By default this list is empty. Example configuration: -``` +```yaml oembed: disable_default_providers: true additional_providers: @@ -1660,7 +1612,7 @@ This homeserver's ReCAPTCHA public key. Must be specified if `enable_registratio enabled. Example configuration: -``` +```yaml recaptcha_public_key: "YOUR_PUBLIC_KEY" ``` --- @@ -1670,7 +1622,7 @@ This homeserver's ReCAPTCHA private key. Must be specified if `enable_registrati enabled. Example configuration: -``` +```yaml recaptcha_private_key: "YOUR_PRIVATE_KEY" ``` --- @@ -1681,7 +1633,7 @@ unless a captcha is answered. Requires a valid ReCaptcha public/private key. Defaults to false. Example configuration: -``` +```yaml enable_registration_captcha: true ``` --- @@ -1691,7 +1643,7 @@ The API endpoint to use for verifying `m.login.recaptcha` responses. Defaults to `https://www.recaptcha.net/recaptcha/api/siteverify`. Example configuration: -``` +```yaml recaptcha_siteverify_api: "https://my.recaptcha.site" ``` --- @@ -1704,7 +1656,7 @@ Config option: `turn_uris` The public URIs of the TURN server to give to clients. Example configuration: -``` +```yaml turn_uris: [turn:example.org] ``` --- @@ -1713,7 +1665,7 @@ Config option: `turn_shared_secret` The shared secret used to compute passwords for the TURN server. Example configuration: -``` +```yaml turn_shared_secret: "YOUR_SHARED_SECRET" ``` ---- @@ -1722,7 +1674,7 @@ Config options: `turn_username` and `turn_password` The Username and password if the TURN server needs them and does not use a token. Example configuration: -``` +```yaml turn_username: "TURNSERVER_USERNAME" turn_password: "TURNSERVER_PASSWORD" ``` @@ -1732,7 +1684,7 @@ Config option: `turn_user_lifetime` How long generated TURN credentials last. Defaults to 1h. Example configuration: -``` +```yaml turn_user_lifetime: 2h ``` --- @@ -1742,8 +1694,8 @@ Whether guests should be allowed to use the TURN server. This defaults to true, VoIP will be unreliable for guests. However, it does introduce a slight security risk as it allows users to connect to arbitrary endpoints without having first signed up for a valid account (e.g. by passing a CAPTCHA). -Example usage: -``` +Example configuration: +```yaml turn_allow_guests: false ``` --- @@ -1758,8 +1710,8 @@ Enable registration for new users. Defaults to false. It is highly recommended t you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration without any verification, you must also set `enable_registration_without_verification` to true. -Example usage: -``` +Example configuration: +```yaml enable_registration: true ``` --- @@ -1768,8 +1720,8 @@ Enable registration without email or captcha verification. Note: this option is as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect unless `enable_registration` is also enabled. -Example usage: -``` +Example configuration: +```yaml enable_registration_without_verification: true ``` --- @@ -1784,8 +1736,8 @@ logged in. By default, this is infinite. -Example usage: -``` +Example configuration: +```yaml session_lifetime: 24h ``` ---- @@ -1802,8 +1754,8 @@ existing sessions until they are refreshed. By default, this is 5 minutes. -Example usage: -``` +Example configuration: +```yaml refreshable_access_token_lifetime: 10m ``` --- @@ -1819,8 +1771,8 @@ changes are not applied to existing sessions until they are refreshed. By default, this is infinite. -Example usage: -``` +Example configuration: +```yaml refresh_token_lifetime: 24h ``` --- @@ -1838,8 +1790,8 @@ retrospectively to existing sessions for users that have already logged in. By default, this is infinite. -Example usage: -``` +Example configuration: +```yaml nonrefreshable_access_token_lifetime: 24h ``` --- @@ -1847,8 +1799,8 @@ Config option: `registrations_require_3pid` If this is set, the user must provide all of the specified types of 3PID when registering. -Example usage: -``` +Example configuration: +```yaml registrations_require_3pid: - email - msisdn @@ -1859,8 +1811,8 @@ Config option: `disable_msisdn_registration` Explicitly disable asking for MSISDNs from the registration flow (overrides `registrations_require_3pid` if MSISDNs are set as required). -Example usage: -``` +Example configuration: +```yaml disable_msisdn_registration: true ``` --- @@ -1869,8 +1821,8 @@ Config option: `allowed_local_3pids` Mandate that users are only allowed to associate certain formats of 3PIDs with accounts on this server, as specified by the `medium` and `pattern` sub-options. -Example usage: -``` +Example configuration: +```yaml allowed_local_3pids: - medium: email pattern: '^[^@]+@matrix\.org$' @@ -1884,8 +1836,8 @@ Config option: `enable_3pid_lookup` Enable 3PIDs lookup requests to identity servers from this server. Defaults to true. -Example usage: -``` +Example configuration: +```yaml enable_3pid_lookup: false ``` --- @@ -1897,8 +1849,8 @@ Note that `enable_registration` must be set to true. Disabling this option will not delete any tokens previously generated. Defaults to false. Set to true to enable. -Example usage: -``` +Example configuration: +```yaml registration_requires_token: true ``` --- @@ -1907,8 +1859,8 @@ Config option: `registration_shared_secret` If set, allows registration of standard or admin accounts by anyone who has the shared secret, even if registration is otherwise disabled. -Example usage: -``` +Example configuration: +```yaml registration_shared_secret: ``` --- @@ -1919,8 +1871,8 @@ Larger numbers increase the work factor needed to generate the hash. The default number is 12 (which equates to 2^12 rounds). N.B. that increasing this will exponentially increase the time required to register or login - e.g. 24 => 2^24 rounds which will take >20 mins. -Example usage: -``` +Example configuration: +```yaml bcrypt_rounds: 14 ``` --- @@ -1930,8 +1882,8 @@ Allows users to register as guests without a password/email/etc, and participate in rooms hosted on this server which have been made accessible to anonymous users. Defaults to false. -Example usage: -``` +Example configuration: +```yaml allow_guest_access: true ``` --- @@ -1943,8 +1895,8 @@ in on this server. (By default, no suggestion is made, so it is left up to the client. This setting is ignored unless `public_baseurl` is also explicitly set.) -Example usage: -``` +Example configuration: +```yaml default_identity_server: https://matrix.org ``` --- @@ -1970,8 +1922,8 @@ examples below. Servers handling the these requests must answer the `/requestToken` endpoints defined by the Matrix Identity Service API [specification](https://matrix.org/docs/spec/identity_service/latest). -Example usage: -``` +Example configuration: +```yaml account_threepid_delegates: email: https://example.com # Delegate email sending to example.com msisdn: http://localhost:8090 # Delegate SMS sending to this local process @@ -1985,8 +1937,8 @@ contents of a third-party directory. Does not apply to server administrators. Defaults to true. -Example usage: -``` +Example configuration: +```yaml enable_set_displayname: false ``` --- @@ -1998,8 +1950,8 @@ of a third-party directory. Does not apply to server administrators. Defaults to true. -Example usage: -``` +Example configuration: +```yaml enable_set_avatar_url: false ``` --- @@ -2010,8 +1962,8 @@ Whether users can change the third-party IDs associated with their accounts Defaults to true. -Example usage: -``` +Example configuration: +```yaml enable_3pid_changes: false ``` --- @@ -2026,8 +1978,8 @@ homeserver. If the room already exists, make certain it is a publicly joinable room, i.e. the join rule of the room must be set to 'public'. You can find more options relating to auto-joining rooms below. -Example usage: -``` +Example configuration: +```yaml auto_join_rooms: - "#exampleroom:example.com" - "#anotherexampleroom:example.com" @@ -2048,8 +2000,8 @@ users cannot be auto-joined since they do not exist. Defaults to true. -Example usage: -``` +Example configuration: +```yaml autocreate_auto_join_rooms: false ``` --- @@ -2065,8 +2017,8 @@ Defaults to true: the room will be joinable from other servers. Set to false to prevent users from other homeservers from joining these rooms. -Example usage: -``` +Example configuration: +```yaml autocreate_auto_join_rooms_federated: false ``` --- @@ -2087,8 +2039,8 @@ If a value of "private_chat" or "trusted_private_chat" is used then Defaults to "public_chat". -Example usage: -``` +Example configuration: +```yaml autocreate_auto_join_room_preset: private_chat ``` --- @@ -2111,8 +2063,8 @@ at the time of creation or subsequently). Note that, if the room already exists, this user must be joined and have the appropriate permissions to invite new members. -Example usage: -``` +Example configuration: +```yaml auto_join_mxid_localpart: system ``` --- @@ -2123,8 +2075,8 @@ guest accounts from being automatically joined to the rooms. Defaults to true. -Example usage: -``` +Example configuration: +```yaml auto_join_rooms_for_guests: false ``` --- @@ -2138,8 +2090,8 @@ raise an error if the registration completes and the username conflicts. Defaults to false. -Example usage: -``` +Example configuration: +```yaml inhibit_user_in_use_error: true ``` --- @@ -2152,8 +2104,8 @@ Config option: `enable_metrics` Set to true to enable collection and rendering of performance metrics. Defaults to false. -Example usage: -``` +Example configuration: +```yaml enable_metrics: true ``` --- @@ -2168,8 +2120,8 @@ this option the sentry server may therefore receive sensitive information, and it in turn may then disseminate sensitive information through insecure notification channels if so configured. -Example usage: -``` +Example configuration: +```yaml sentry: dsn: "..." ``` @@ -2183,8 +2135,8 @@ Currently the only option is `known_servers`, which publishes servers this homeserver knows about, including itself. May cause performance problems on large homeservers. -Example usage: -``` +Example configuration: +```yaml metrics_flags: known_servers: true ``` @@ -2195,8 +2147,8 @@ Whether or not to report anonymized homeserver usage statistics. This is origina set when generating the config. Set this option to true or false to change the current behavior. -Example usage: -``` +Example configuration: +```yaml report_stats: true ``` --- @@ -2205,8 +2157,8 @@ Config option: `report_stats_endpoint` The endpoint to report the anonymized homeserver usage statistics to. Defaults to https://matrix.org/report-usage-stats/push -Example usage: -``` +Example configuration: +```yaml report_stats_endpoint: https://example.com/report-usage-stats/push ``` --- @@ -2234,8 +2186,8 @@ To change the default behavior, use the following sub-options: * `additional_event_types`: Additional state event types to share with users when they are invited to a room. By default, this list is empty (so only the default event types are shared). -Example usage: -``` +Example configuration: +```yaml room_prejoin_state: disable_default_event_types: true additional_event_types: @@ -2258,8 +2210,8 @@ user. (This also means that the puppeted user will count as an "active" user for the purpose of monthly active user tracking - see `limit_usage_by_mau` etc above.) -Example usage: -``` +Example configuration: +```yaml track_puppeted_user_ips: true ``` --- @@ -2267,8 +2219,8 @@ Config option: `app_service_config_files` A list of application service config files to use. -Example usage: -``` +Example configuration: +```yaml app_service_config_files: - app_service_1.yaml - app_service_2.yaml @@ -2279,8 +2231,8 @@ Config option: `track_appservice_user_ips` Defaults to false. Set to true to enable tracking of application service IP addresses. Implicitly enables MAU tracking for application service users. -Example usage: -``` +Example configuration: +```yaml track_appservice_user_ips: true ``` --- @@ -2290,8 +2242,8 @@ A secret which is used to sign access tokens. If none is specified, the `registration_shared_secret` is used, if one is given; otherwise, a secret key is derived from the signing key. -Example usage: -``` +Example configuration: +```yaml macaroon_secret_key: ``` --- @@ -2301,8 +2253,8 @@ A secret which is used to calculate HMACs for form values, to stop falsification of values. Must be specified for the User Consent forms to work. -Example usage: -``` +Example configuration: +```yaml form_secret: ``` --- @@ -2314,8 +2266,8 @@ Config option: `signing_key_path` Path to the signing key to sign messages with. -Example usage: -``` +Example configuration: +```yaml signing_key_path: "CONFDIR/SERVERNAME.signing.key" ``` --- @@ -2329,8 +2281,8 @@ it was last used. It is possible to build an entry from an old `signing.key` file using the `export_signing_key` script which is provided with synapse. -Example usage: -``` +Example configuration: +```yaml old_signing_keys: "ed25519:id": { key: "base64string", expired_ts: 123456789123 } ``` @@ -2342,8 +2294,8 @@ Used to set the `valid_until_ts` in `/key/v2` APIs. Determines how quickly servers will query to check which keys are still valid. Defaults to 1d. -Example usage: -``` +Example configuration: +```yaml key_refresh_interval: 2d ``` --- @@ -2376,16 +2328,16 @@ Options for each entry in the list include: and are sure that your network environment provides a secure connection to the key server, you can set this to `true` to override this behaviour. -Example usage #1: -``` +Example configuration #1: +```yaml trusted_key_servers: - server_name: "my_trusted_server.example.com" verify_keys: "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr" - server_name: "my_other_trusted_server.example.com" ``` -Example usage #2: -``` +Example configuration #2: +```yaml trusted_key_servers: - server_name: "matrix.org" ``` @@ -2395,8 +2347,8 @@ Config option: `suppress_key_server_warning` Set the following to true to disable the warning that is emitted when the `trusted_key_servers` include 'matrix.org'. See above. -Example usage: -``` +Example configuration: +```yaml suppress_key_server_warning: true ``` --- @@ -2407,8 +2359,8 @@ defaults to the server signing key. Can contain multiple keys, one per line. -Example usage: -``` +Example configuration: +```yaml key_server_signing_keys_path: "key_server_signing_keys.key" ``` --- @@ -2424,6 +2376,7 @@ disable the regular login/registration flows: You will also want to investigate the settings under the "sso" configuration section below. + --- Config option: `saml2_config` @@ -2489,7 +2442,7 @@ the IdP to use an ACS location of `https://:/_synapse/client/saml2/authn_response`. Example configuration: -``` +```yaml saml2_config: sp_config: metadata: @@ -2704,7 +2657,7 @@ Options for each entry include: 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" @@ -2721,7 +2674,7 @@ above, the `family_name` claim MUST be "Stephensson", but the `groups` claim MUST contain "admin". Example configuration: -``` +```yaml oidc_providers: # Generic example # @@ -2766,7 +2719,7 @@ Has the following sub-options: All of the listed attributes must match for the login to be permitted. Example configuration: -``` +```yaml cas_config: enabled: true server_url: "https://cas-server.com" @@ -2805,7 +2758,7 @@ Options include: Example configuration: -``` +```yaml sso: client_whitelist: - https://riot.im/develop @@ -2847,7 +2800,7 @@ Additional sub-options for this setting include: validation will fail without configuring audiences. Example configuration: -``` +```yaml jwt_config: enabled: true secret: "provided-by-your-issuer" @@ -2883,8 +2836,8 @@ This setting has the following sub-options: Defaults to false. -Example usage: -``` +Example configuration: +```yaml password_config: enabled: false localdb_enabled: false @@ -2916,7 +2869,7 @@ adding a 3PID). Use the `session_timeout` sub-option here to change the time allowed for credential validation. Example configuration: -``` +```yaml ui_auth: session_timeout: "15s" ``` @@ -2990,8 +2943,8 @@ This setting has the following sub-options: * `email_validation`: Subject to use when sending a verification email to assert an address's ownership. Defaults to "[%(server_name)s] Validate your email" -Example usage: -``` +Example configuration: +```yaml email: smtp_host: mail.server smtp_port: 587 @@ -3046,8 +2999,8 @@ This option has a number of sub-options. They are as follows: rooms with unread messages in them. Set to false to instead send the number of unread messages. -Example usage: -``` +Example configuration: +```yaml push: include_content: false group_unread_count_by_room: false @@ -3074,8 +3027,8 @@ 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 usage: -``` +Example configuration: +```yaml encryption_enabled_by_default_for_room_type: invite ``` --- @@ -3083,8 +3036,8 @@ Config option: `enable_group_creation` Set to true to allow non-server-admin users to create groups on this server -Example usage: -``` +Example configuration: +```yaml enable_group_creation: true ``` --- @@ -3093,8 +3046,8 @@ Config option: `group_creation_prefix` If enabled/present, non-server admins can only create groups with local parts starting with this prefix. -Example usage: -``` +Example configuration: +```yaml group_creation_prefix: "unofficial_" ``` --- @@ -3121,8 +3074,8 @@ This option has the following sub-options: If set to true, local users are more likely to appear above remote users when searching the user directory. Defaults to false. -Example usage: -``` +Example configuration: +```yaml user_directory: enabled: false search_all_users: true @@ -3162,8 +3115,8 @@ Parts of this section are required if enabling the `consent` resource under for an account. Has no effect unless `require_at_registration` is enabled. Defaults to "Privacy Policy". -Example usage: -``` +Example configuration: +```yaml user_consent: template_dir: res/templates/privacy version: 1.0 @@ -3189,8 +3142,8 @@ for more. so may cause certain features (such as the room directory) not to work correctly. Defaults to true. -Example usage: -``` +Example configuration: +```yaml stats: enabled: false ``` @@ -3210,8 +3163,8 @@ Sub-options for this setting include: * `system_mxid_avatar_url`: set the avatar for the "notices" user * `room_name`: set the room name of the server notices room -Example usage: -``` +Example configuration: +```yaml server_notices: system_mxid_localpart: notices system_mxid_display_name: "Server Notices" @@ -3225,8 +3178,8 @@ 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 usage: -``` +Example configuration: +```yaml enable_room_list_search: false ``` --- @@ -3252,7 +3205,7 @@ Options for the rules include: * `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" @@ -3282,7 +3235,7 @@ Options for the rules include: * `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: "*" @@ -3315,8 +3268,8 @@ Sub-options include: 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 usage: -``` +Example configuration: +```yaml opentracing: enabled: true homeserver_whitelist: @@ -3342,8 +3295,8 @@ Config option: `send_federation` Controls sending of outbound federation transactions on the main process. Set to false if using a federation sender worker. Defaults to true. -Example usage: -``` +Example configuration: +```yaml send_federation: false ``` --- @@ -3357,8 +3310,8 @@ changed all federation sender workers must be stopped at the same time and then started, to ensure that all instances are running with the same config (otherwise events may be dropped). -Example usage: -``` +Example configuration: +```yaml federation_sender_instances: - federation_sender1 ``` @@ -3368,8 +3321,8 @@ Config option: `instance_map` When using workers this should be a map from worker name to the HTTP replication listener of the worker, if configured. -Example usage: -``` +Example configuration: +```yaml instance_map: worker1: host: localhost @@ -3382,8 +3335,8 @@ Experimental: When using workers you can define which workers should handle event persistence and typing notifications. Any worker specified here must also be in the `instance_map`. -Example usage: -``` +Example configuration: +```yaml stream_writers: events: worker1 typing: worker1 @@ -3394,8 +3347,8 @@ Config option: `run_background_task_on` The worker that is used to run background tasks (e.g. cleaning up expired data). If not provided this defaults to the main process. -Example usage: -``` +Example configuration: +```yaml run_background_tasks_on: worker1 ``` --- @@ -3406,8 +3359,8 @@ from workers. By default this is unused and traffic is not authenticated. -Example usage: -``` +Example configuration: +```yaml worker_replication_secret: "secret_secret" ``` Config option: `redis` @@ -3420,8 +3373,8 @@ This setting has the following sub-options: localhost and 6379 * `password`: Optional password if configured on the Redis instance. -Example usage: -``` +Example configuration: +```yaml redis: enabled: true host: localhost @@ -3449,7 +3402,7 @@ This setting has the following sub-options: Set a size to change the default. Example configuration: -``` +```yaml background_updates: background_update_duration_ms: 500 sleep_enabled: false