144 lines
4.0 KiB
Markdown
144 lines
4.0 KiB
Markdown
# 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)
|