# Configuration
- [Concepts](#concepts)
  - [Syntax](#syntax)
- [Matrix](#matrix)
- [Server](#server)
- [Storage](#storage)
- [Identity stores](#identity-stores)
- [3PID Validation sessions](#3pid-validation-sessions)
- [Notifications](#notifications)

## Concepts
### Syntax
The configuration file is [YAML](http://yaml.org/) based:
```yaml
my:
  config:
    item: 'value'

```

When referencing keys in all documents, a property-like shorthand will be used. The shorthand for the above example would be `my.config.item`

## Matrix
`matrix.domain`
Matrix domain name, same as the Homeserver, used to build appropriate Matrix IDs |

---

`matrix.identity.servers`
Namespace to create arbitrary list of Identity servers, usable in other parts of the configuration |

Example:
```yaml
matrix:
  identity:
    servers:
      myOtherServers:
        - 'https://other1.example.org'
        - 'https://other2.example.org'
```
Create a list under the label `myOtherServers` containing two Identity servers: `https://other1.example.org` and `https://other2.example.org`.

## Server
- `server.name`: Public hostname of ma1sd, if different from the Matrix domain.
- `server.port`: HTTP port to listen on (unencrypted)
- `server.publicUrl`: Defaults to `https://{server.name}`

## Unbind (MSC1915)
- `session.policy.unbind.enabled`: Enable or disable unbind functionality (MSC1915). (Defaults to true).

## Hash lookups, Term and others (MSC2140, MSC2134)
See the [dedicated document](MSC2140_MSC2134.md) for configuration.

*Warning*: Unbind check incoming request by two ways:
- session validation.
- request signature via `X-Matrix` header and uses `server.publicUrl` property to construct the signing json;
Commonly the `server.publicUrl` should be the same value as the `trusted_third_party_id_servers` property in the synapse config.

## Storage
### SQLite
```yaml
storage:
  backend: sqlite # default
  provider:
    sqlite:
      database: /var/lib/ma1sd/store.db #  Absolute location of the SQLite database
```

### Postgresql
```yaml
storage:
  backend: postgresql
  provider:
    postgresql:
      database: //localhost:5432/ma1sd
      username: ma1sd
      password: secret_password
```
See [the migration instruction](migration-to-postgresql.md) from sqlite to postgresql


## Logging
```yaml
logging:
  root: error     # default level for all loggers (apps and thirdparty libraries)
  app: info       # log level only for the ma1sd
  requests: false # log request and response
```

Possible value: `trace`, `debug`, `info`, `warn`, `error`, `off`.

Default value for root level: `info`.

Value for app level can be specified via `MA1SD_LOG_LEVEL` environment variable, configuration or start options.

Default value for app level: `info`.

| start option | equivalent configuration |
| --- | --- |
|  | app: info |
| -v | app: debug |
| -vv | app: trace |

#### WARNING

The setting `logging.requests` *MUST NOT* be used in production due it prints full unmasked request and response into the log and can be cause of the data leak. 
This setting can be used only to testing and debugging errors.

## Identity stores
See the [Identity stores](stores/README.md) for specific configuration

## 3PID Validation sessions
See the dedicated documents:
- [Flow](threepids/session/session.md)
- [Branding](threepids/session/session-views.md)

## Notifications
- `notification.handler.<3PID medium>`: Handler to use for the given 3PID medium. Repeatable.

Example:
```yaml
notification:
  handler:
    email: 'sendgrid'
    msisdn: 'raw'
```
- Emails notifications would use the `sendgrid` handler, which define its own configuration under `notification.handlers.sendgrid`
- Phone notification would use the `raw` handler, basic default built-in handler in ma1sd

### Handlers
- `notification.handers.<handler ID>`: Handler-specific configuration for the given handler ID. Repeatable.

Example:
```yaml
notification:
  handlers:
    raw: ...
    sendgrid: ...
```

Built-in:
- [Raw](threepids/notification/basic-handler.md)
- [SendGrid](threepids/notification/sendgrid-handler.md)