mxids/docs/configure.md

Configuration

• Concepts
  • Syntax
• Matrix
• Server
• Storage
• Identity stores
• 3PID Validation sessions
• Notifications

Concepts

Syntax

The configuration file is YAML based:

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:

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

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

Postgresql

storage:
  backend: postgresql
  provider:
    postgresql:
      database: //localhost:5432/ma1sd
      username: ma1sd
      password: secret_password

See the migration instruction from sqlite to postgresql

Logging

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 for specific configuration

3PID Validation sessions

See the dedicated documents:

• Flow
• Branding

Notifications

• notification.handler.<3PID medium>: Handler to use for the given 3PID medium. Repeatable.

Example:

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:

notification:
  handlers:
    raw: ...
    sendgrid: ...

Built-in:

• Raw
• SendGrid