config_documentation.md

# Configuring Synapse

This is intended as a guide to the Synapse configuration. The behavior of a Synapse instance can be modified 
through the many configuration settings documented here — each config option is explained, 
including what the default is, how to change the default and what sort of behaviour the setting governs.
Also included is an example configuration for each setting. If you don't want to spend a lot of time 
thinking about options, the config as generated sets sensible defaults for all values. Do note however that the
database defaults to SQLite, which is not recommended for production usage. You can read more on this subject 
[here](../../setup/installation.md#using-postgresql).

## Config Conventions

Configuration options that take a time period can be set using a number
followed by a letter. Letters have the following meanings:

* `s` = second
* `m` = minute
* `h` = hour
* `d` = day
* `w` = week
* `y` = year

For example, setting `redaction_retention_period: 5m` would remove redacted
messages from the database after 5 minutes, rather than 5 months.

### YAML 
The configuration file is a [YAML](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 
   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:
   ```yaml
   pid_file: DATADIR/homeserver.pid
   ```
   Example #2:
   ```yaml
   #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: 
  ```yaml
  presence:
    enabled: false
  ```
  Example #2:
  ```yaml
  presence:
  enabled: false
  ```
  In this manual, all top-level settings (ones with no indentation) are identified 
  at the beginning of their section (i.e. "Config option: `example_setting`") and 
  the sub-options, if any, are identified and listed in the body of the section. 
  In addition, each setting has an example of its usage, with the proper indentation
  shown. 

## Contents
[Modules](#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)

[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 [here](../../modules/index.md) for more
documentation on how to configure or create custom modules for Synapse.


---
Config option: `modules`

Use the `module` sub-option to add modules under this option to extend functionality. 
The `module` setting then has a sub-option, `config`, which can be used to define some configuration
for the `module`.

Defaults to none.

Example configuration:
```yaml
modules:
  - module: my_super_module.MySuperClass
    config:
      do_thing: true
  - module: my_other_super_module.SomeClass
    config: {}
```
---
## Server ##

Define your homeserver name and other base options.

---
Config option: `server_name`

This sets the public-facing domain of the server.

The `server_name` name will appear at the end of usernames and room addresses
created on your server. For example if the `server_name` was example.com,
usernames on your server would be in the format `@user:example.com`

In most cases you should avoid using a matrix specific subdomain such as
matrix.example.com or synapse.example.com as the `server_name` for the same
reasons you wouldn't use user@email.example.com as your email address.
See [here](../../delegate.md)
for information on how to host Synapse on a subdomain while preserving
a clean `server_name`.

The `server_name` cannot be changed later so it is important to
configure this correctly before you start Synapse. It should be all
lowercase and may contain an explicit port.

There is no default for this option. 
 
Example configuration #1:
```yaml
server_name: matrix.org 
```
Example configuration #2:
```yaml
server_name: localhost:8080
```
---
Config option: `pid_file`

When running Synapse as a daemon, the file to store the pid in. Defaults to none.

Example configuration:
```yaml
pid_file: DATADIR/homeserver.pid
```
---
Config option: `web_client_location`

The absolute URL to the web client which `/` will redirect to. Defaults to none. 

Example configuration:
```yaml
web_client_location: https://riot.example.com/
```
---
Config option: `public_baseurl`

The public-facing base URL that clients use to access this Homeserver (not
including _matrix/...). This is the same URL a user might enter into the
'Custom Homeserver URL' field on their client. If you use Synapse with a
reverse proxy, this should be the URL to reach Synapse via the proxy.
Otherwise, it should be the URL to reach Synapse's client HTTP listener (see
'listeners' below).

Defaults to `https://<server_name>/`.