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

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

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