config_documentation.md

---
## Federation ##

Options related to federation.

---
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:
```yaml
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:
```yaml
federation_metrics_domains:
  - matrix.org
  - example.com
```
---
Config option: `allow_profile_lookup_over_federation`

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.

Example configuration:
```yaml
allow_profile_lookup_over_federation: false
```
---
Config option: `allow_device_name_lookup_over_federation`

Set this option to true to allow device display name lookup over federation. By default, the
Federation API prevents other homeservers from obtaining the display names of any user devices
on this homeserver.

Example configuration:
```yaml
allow_device_name_lookup_over_federation: true
```
---
## Caching ##

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.

Example configuration:
```yaml
event_cache_size: 15K
```
---
Config option: `cache` and associated values

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 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
  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.
* `cache_autotuning` and its sub-options `max_cache_memory_usage`, `target_cache_memory_usage`, and
   `min_cache_ttl` work in conjunction with each other to maintain a balance between cache memory 
   usage and cache entry availability. You must be using [jemalloc](https://github.com/matrix-org/synapse#help-synapse-is-slow-and-eats-all-my-ramcpu) 
   to utilize this option, and all three of the options must be specified for this feature to work.
     * `max_cache_memory_usage` sets a ceiling on how much memory the cache can use before caches begin to be continuously evicted.
        They will continue to be evicted until the memory usage drops below the `target_memory_usage`, set in
        the flag below, or until the `min_cache_ttl` is hit.
     * `target_memory_usage` sets a rough target for the desired memory usage of the caches.
     * `min_cache_ttl` sets a limit under which newer cache entries are not evicted and is only applied when
        caches are actively being evicted/`max_cache_memory_usage` has been exceeded. This is to protect hot caches
        from being emptied while Synapse is evicting due to memory.

Example configuration:
```yaml
caches:
  global_factor: 1.0
  per_cache_factors:
    get_users_who_share_room_with_user: 2.0
  sync_response_cache_duration: 2m
  cache_autotuning:
    max_cache_memory_usage: 1024M
    target_cache_memory_usage: 758M
    min_cache_ttl: 5m
```

### Reloading cache factors

The cache factors (i.e. `caches.global_factor` and `caches.per_cache_factors`)  may be reloaded at any time by sending a
[`SIGHUP`](https://en.wikipedia.org/wiki/SIGHUP) signal to Synapse using e.g.

```commandline
kill -HUP [PID_OF_SYNAPSE_PROCESS]
```

If you are running multiple workers, you must individually update the worker 
config file and send this signal to each worker process.

If you're using the [example systemd service](https://github.com/matrix-org/synapse/blob/develop/contrib/systemd/matrix-synapse.service)
file in Synapse's `contrib` directory, you can send a `SIGHUP` signal by using
`systemctl reload matrix-synapse`.

---
## Database ##
Config options related to database settings.

---
Config option: `database`

The `database` setting defines the database that synapse uses to store all of
its data.

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. 

* `txn_limit` gives the maximum number of transactions to run per connection
  before reconnecting. Defaults to 0, which means no limit.

* `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](../../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 more information on using Synapse with Postgres,
see [here](../../postgres.md).

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
```
---
## Logging ##
Config options related to logging. 

---
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"
```
---
## 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.
---
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`.

Example configuration:
```yaml
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`. 

Example configuration:
```yaml
rc_registration:
  per_second: 0.15
  burst_count: 2
```
---
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`.

Example configuration:
```yaml
rc_registration_token_validity:
  per_second: 0.3
  burst_count: 6
```   
---
Config option: `rc_login`

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:
```yaml
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`

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. 

Example configuration:
```yaml
rc_admin_redaction:
  per_second: 1
  burst_count: 50
```
---
Config option: `rc_joins`

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`.

* `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:
```yaml
rc_joins:
  local:
    per_second: 0.2
    burst_count: 15
  remote:
    per_second: 0.03
    burst_count: 12
```
---
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`.

Example configuration:
```yaml
rc_3pid_validation:
  per_second: 0.003
  burst_count: 5
```
---
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`. 

Client requests that invite user(s) when [creating a
room](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom)
will count against the `rc_invites.per_room` limit, whereas
client requests to [invite a single user to a
room](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite)
will count against both the `rc_invites.per_user` and `rc_invites.per_room` limits.

Federation requests to invite a user will count against the `rc_invites.per_user`
limit only, as Synapse presumes ratelimiting by room will be done by the sending server.

The `rc_invites.per_user` limit applies to the *receiver* of the invite, rather than the
sender, meaning that a `rc_invite.per_user.burst_count` of 5 mandates that a single user
cannot *receive* more than a burst of 5 invites at a time.

Example configuration:
```yaml
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`.

Example configuration:
```yaml
rc_third_party_invite:
  per_second: 0.2
  burst_count: 10
```
---
Config option: `rc_federation`

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.
* `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:
```yaml
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`

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
into fewer transactions. Defaults to 50. 

Example configuration:
```yaml
federation_rr_transactions_per_room_per_second: 40
```
---
## 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. 
Set to false if you are using a separate media store worker.

Example configuration:
```yaml
enable_media_repo: false
```
---
Config option: `media_store_path`

Directory where uploaded images and attachments are stored.

Example configuration:
```yaml
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 sub-options are:
* `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:
```yaml
media_storage_providers:
  - module: file_system
    store_local: false
    store_remote: false
    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 [here](../../reverse_proxy.md) for more on using a reverse proxy with Synapse. 

Example configuration:
```yaml
max_upload_size: 60M
```
---
Config option: `max_image_pixels`

Maximum number of pixels that will be thumbnailed. Defaults to 32M.

Example configuration:
```yaml
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:
```yaml
dynamic_thumbnails: true
```
---
Config option: `thumbnail_sizes`  

List of thumbnails to precalculate when an image is uploaded. Associated sub-options are:
* `width`
* `height`
* `method`: i.e. `crop`, `scale`, etc.

Example configuration:
```yaml
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 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
```
---
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 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'
  - '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. Defaults to none. 

Example configuration:
```yaml
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 
[here](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
blacklisted.

Example configuration:
```yaml
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:
```yaml
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:
```yaml
 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. 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. 

Example configuration:
```yaml
oembed:
  disable_default_providers: true
  additional_providers:
    - oembed/my_providers.json
```
---
## Captcha ##

See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha.

---
Config option: `recaptcha_public_key`

This homeserver's ReCAPTCHA public key. Must be specified if `enable_registration_captcha` is 
enabled.

Example configuration:
```yaml
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:
```yaml
recaptcha_private_key: "YOUR_PRIVATE_KEY"
```
---
Config option: `enable_registration_captcha`

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.

Example configuration:
```yaml
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:
```yaml
recaptcha_siteverify_api: "https://my.recaptcha.site"
```
---
## TURN ##
Options related to adding a TURN server to Synapse.

---
Config option: `turn_uris`

The public URIs of the TURN server to give to clients.

Example configuration:
```yaml
turn_uris: [turn:example.org]
```
---
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"
```
----
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"
```
---
Config option: `turn_user_lifetime`

How long generated TURN credentials last. Defaults to 1h.

Example configuration:
```yaml
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 configuration:
```yaml
turn_allow_guests: false
```
---
## Registration ##

Registration can be rate-limited using the parameters in the [Ratelimiting](#ratelimiting) section of this manual.

---
Config option: `enable_registration`

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 configuration:
```yaml
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 configuration:
```yaml
enable_registration_without_verification: 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 configuration:
```yaml
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](user_authentication/refresh_tokens.md).

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 configuration:
```yaml
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.

Example configuration:
```yaml
refresh_token_lifetime: 24h
```
---
Config option: `nonrefreshable_access_token_lifetime`

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.

Example configuration:
```yaml
nonrefreshable_access_token_lifetime: 24h
```
---
Config option: `registrations_require_3pid`

If this is set, the user must provide all of the specified types of 3PID when registering.

Example configuration:
```yaml
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).

Example configuration:
```yaml
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` sub-options.

Example configuration:
```yaml
allowed_local_3pids:
  - medium: email
    pattern: '^[^@]+@matrix\.org$'
  - medium: email
    pattern: '^[^@]+@vector\.im$'
  - medium: msisdn
    pattern: '\+44'
```
---
Config option: `enable_3pid_lookup`

Enable 3PIDs lookup requests to identity servers from this server. Defaults to true.

Example configuration:
```yaml
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](../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.  

Example configuration:
```yaml
registration_requires_token: true
```
---
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 configuration:
```yaml
registration_shared_secret: <PRIVATE STRING>
```
---
Config option: `bcrypt_rounds`

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 configuration:
```yaml
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.

Example configuration:
```yaml
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.

(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 configuration:
```yaml
default_identity_server: https://matrix.org