cdist-type__matrix_synapse(7)

NAME

cdist-type__matrix_synapse - Install and configure Synapse, a Matrix homeserver

DESCRIPTION

This type installs and configures the Synapse Matrix homeserver. This is a signleton type.

REQUIRED PARAMETERS

server-name

Name of your homeserver (e.g. ungleich.ch) used as part of your MXIDs. This value cannot be changed later on.

base-url

Public URL of your homeserver (e.g. http://matrix.ungleich.ch).

database-engine

‘sqlite3’ or ‘psycopg2’ (= Postgresql).

database-name

Path to database file if SQLite3 is used or database name if PostgresSQL is used.

OPTIONAL PARAMETERS

database-host

Database node address, only used with PostgresSQL.

database-user

Database user, only used with PostgresSQL.

database-password

Database password, only used with PostgresSQL.

database-connection-pool-min

The minimum number of connections in pool, defaults to 3.

database-connection-pool-max

The maximum number of connections in pool, defaults to 5.

ldap-uri

Address of your LDAP server.

ldap-base-dn

Base DN of your LDAP tree.

ldap-uid-attribute

LDAP attribute mapping to Synapse’s uid field, default to uid.

ldap-mail-attribute

LDAP attribute mapping to Synapse’s mail field, default to mail.

ldap-name-attribute

LDAP attribute mapping to Synapse’s name field, default to givenName.

ldap-bind-dn

User used to authenticate against your LDAP server in ‘search’ mode.

ldap-bind-password

Password used to authenticate against your LDAP server in ‘search’ mode.

ldap-filter

LDAP user filter, defaulting to (objectClass=posixAccount).

tls-cert

Path to PEM-encoded X509 TLS certificate. Not needed if TLS termination is handled by a reverse Proxy such as NGINX.

tls-private-key

Path to PEM-encoded TLS private key. Not needed if TLS termination is handled by a reverse Proxy such as NGINX.

smtp-host

The hostname of the outgoing SMTP server to use. Defaults to ‘localhost’.

smtp-port

The port on the mail server for outgoing SMTP. Defaults to 25.

smtp-user

Username for authentication to the SMTP server. By default, no authentication is attempted.

smtp-password

Password for authentication to the SMTP server. By default, no authentication is attempted.

notification-from

From address to use when sending emails. Defaults to “%(app)s <no-reply@$SERVER_NAME>”.

message-max-lifetime

Default retention policy. If set, Synapse will apply it to rooms that lack the ‘m.room.retention’ state event. Ignored if enable-message-retention-policy is not set. Defaults to 1y.

web-client-url

Custom URL for client links within the email notifications. By default links will be based on “https://matrix.to”.

global-cache-factor

Controls the global cache factor, which is the default cache factor for all caches if a specific factor for that cache is not otherwise set. Defaults to 0.5, which will half the size of all caches.

event-cache-size

The number of events to cache in memory. Not affected by caches.global_factor. Defaults to 10K.

remote-room-complexity-threshold

The limit above which rooms cannot be joined when limit-remote-room-complexity is set. Room complexity is an arbitrary measure based on factors such as the number of users in the room. The default is 1.0.

room-encrypt-policy

Controls whether locally-created rooms should be end-to-end encrypted by default. Possible options are “all” (any locally-created room), “invite” (any room created with the private_chat or trusted_private_chat room creation presets , and “off” (this option will take no effect). Defaults to “off”.

turn-uri

URI to TURN server, can be provided multiple times if there is more than one server.

turn-shared-secret

Shared secret used to access the TURN REST API.

turn-username

Username used to authenticate against the TURN server if needed / a shared secret token is not used.

turn-password

Password used to authenticate against the TURN server if needed / a shared secret token is not used.

turn-user-lifetime

Lifetime of TURN credentials. Defaults to 1h.

max-upload-size

Maximum size for user-uploaded files. Defaults to 10M.

rc-message-per-second

Message rate-limiting (per second). Defaults to 0.17.

rc-message-burst

Message rate-limiting (burst). Defaults to 3.

rc-login-per-second

Login rate-limiting (per-second). Defaults to 0.17.

rc-login-burst

Login rate-limiting (burst). Defaults to 3.

registration-allows-email-pattern

Only allow email addresses matching specified filter. Can be specified multiple times. A pattern must look like .*@vector.im.

disable-displayname-changes

Whether users are allowed to change their displayname after it has been initially set.

disable-3pid-changes

Whether users can change the 3PIDs associated with their accounts (email address and msisdn).

auto-join-room

Room where newly-registered users are automatically added. Can be specified multiple times.

app-service-config-file

Path (on remote) of an application service configuration file to load. Can be specified multiple times.

worker-replication-secret

A shared secret used by the replication APIs to authenticate HTTP requests from workers. Ignored if worker-mode is not set. By default this is unused and traffic is not authenticated.

background-tasks-worker

The worker that is used to run background tasks (e.g. cleaning up expired data). If not provided this defaults to the main process.

outbound-federation-worker

Worker to be used for sending federation requests. Can be specified multiple times. Disables sending outbound federation requests from the master process.

registration-shared-secret

If set, allows registration of standard or admin accounts by anyone who has the shared secret, even if registration is otherwise disabled.

bind-address

Address used to bind the synapse listeners. Can be specified multiple times. Defaults to ‘::1’ and ‘127.0.0.1’.

saml2-idp-metadata-url

HTTP(S) url to SAML2 Identity Provider (IdP), used for Single Sign On (SSO) logic.

saml2-sp-key

Path to PEM-formatted key file for use by PySAML2.

saml2-sp-cert

Path to PEM-formatted cert file for use by PySAML2.

saml2-mapping-provider-module

Name of custom Python module used to map SAML2 attributes to synapse internals.

saml2-mapping-provider-extra-settings

Extra YAML-formatted key/pair values provided as configuration to the SAML2 mapping provider module (e.g. ‘key: value’). Can be specified multiple times.

sso-template-dir

Directory used to source SSO-related HTML templates.

extra-setting

Arbitrary string to be added to the configuration file. Can be specified multiple times.

BOOLEAN PARAMETERS

enable-registrations

Enables user registration on the homeserver.

enable-ldap-auth

Enables ldap-backed authentication.

ldap-use-starttls

Use STARTTLS when connection to the LDAP server.

report-stats

Whether or not to report anonymized homeserver usage statistics.

expose-metrics

Expose metrics endpoint for Prometheus.

enable-notifications

Enable mail notifications (see smtp-* optinal parameters).

smtp-use-starttls

Use STARTTLS when connection to the SMTP server.

disable-federation

Disable federation to the broader matrix network.

registration-require-email

Make email a required field on registration.

allow-public-rooms-over-federation

Allow other homeservers to fetch this server’s public room directory.

allow-public-rooms-without-auth

If set to ‘false’, requires authentication to access the server’s public rooms directory through the client API.

enable-server-notices

Enable the server notices room.

enable-3pid-lookups

Enable 3PIDs lookup requests to identity servers from this server.

allow-guest-access

Allows users to register as guests without a password/email/etc, and participate in rooms hosted on this server which have been made accessible to anonymous users.

limit-remote-room-complexity

When this is enabled, the room “complexity” will be checked before a user joins a new remote room. If it is above the complexity limit (see remote-room-complexity-threshold parameter), the server will disallow joining, or will instantly leave.

disable-presence

Disable presence tracking on this homeserver.

user-directory-search-all-users

Defines whether to search all users visible to your HS when searching the user directory, rather than limiting to users visible in public rooms. If you set it True, you’ll have to rebuild the user_directory search indexes, see https://github.com/matrix-org/synapse/blob/master/docs/user_directory.md.

enable-message-retention-policy

If this feature is enabled, Synapse will regularly look for and purge events which are older than the room’s maximum retention period. Synapse will also filter events received over federation so that events that should have been purged are ignored and not stored again. See message-max-lifetime flag.

worker-mode

For small instances it recommended to run Synapse in the default monolith mode. For larger instances where performance is a concern it can be helpful to split out functionality into multiple separate python processes. These processes are called ‘workers’. Please read the WORKER MODE section of this manpage before enabling, as extra work and considerations are required.

PERFORMANCE

The Synapse server is not very performant (initial implementation, pretty resource hungry, etc.) and will eventually be replaced by Dendrite. The following parameters (see above descriptions) will help you with performance tuning:

  • global-cache-factor

  • event-cache-size

  • disable-presence

  • limit-remote-room-complexity and remote-room-complexity-threshold

WORKER MODE

Worker mode allows to move some processing out of the main synapse process for horizontal scaling. You are expected to use the cdist-type__matrix_synapse_worker(7) type to set up workers when the worker-mode flag is set.

Worker mode depend on the following components:

  • A working redis server

  • The hiredis python package (python3-hiredis on debian, not packaged in alpine as of 2021-02-17).

  • The txredisapi python package, which is not packaged on debian nor alpine as of 2021-02-17.

The current way to install the above two python packages (if not packaged in your distribution) is sadly to use pip (see cdist-type__python_pip(7) core cdist type).

It is also recommended to first take a look at:

EXAMPLES

__matrix_synapse --server-name ungleich.ch \
  --base-url https://matrix.ungleich.ch \
  --database-engine sqlite3 \
  --database-name /var/lib/matrix-syanpse/homeserver.db

You might also be interested in ungleich’s __ungleich_matrix meta-type.

SEE ALSO

AUTHORS

Timothée Floure <timothee.floure@ungleich.ch>

COPYING

Copyright (C) 2019-2021 Timothée Floure. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.