cdist-type__matrix_synapse - Install and configure Synapse, a Matrix homeserver
This type install and configure the Synapse Matrix homeserver. This is a signleton type.
Name of your homeserver (e.g. ungleich.ch) used as part of your MXIDs. This value cannot be changed later on.
Public URL of your homeserver (e.g. http://matrix.ungleich.ch).
‘sqlite3’ or ‘psycopg2’ (= Postgresql).
Path to database file if SQLite3 is used or database name if PostgresSQL is used.
Database node address, only used with PostgresSQL.
Database user, only used with PostgresSQL.
Database password, only used with PostgresSQL.
The minimum number of connections in pool, defaults to 3.
The maximum number of connections in pool, defaults to 5.
Address of your LDAP server.
Base DN of your LDAP tree.
LDAP attriute mapping to Synapse’s uid field, default to uid.
LDAP attriute mapping to Synapse’s mail field, default to mail.
LDAP attriute mapping to Synapse’s name field, default to givenName.
User used to authenticate against your LDAP server in ‘search’ mode.
Password used to authenticate against your LDAP server in ‘search’ mode.
LDAP user filter, defaulting to (objectClass=posixAccount).
Path to PEM-encoded X509 TLS certificate. Not needed if TLS termination is handled by a reverse Proxy such as NGINX.
Path to PEM-encoded TLS private key. Not needed if TLS termination is handled by a reverse Proxy such as NGINX.
The hostname of the outgoing SMTP server to use. Defaults to ‘localhost’.
# The port on the mail server for outgoing SMTP. Defaults to 25.
Username for authentication to the SMTP server. By default, no authentication is attempted.
Password for authentication to the SMTP server. By default, no authentication is attempted.
From address to use when sending emails. Defaults to “%(app)s <no-reply@$SERVER_NAME>”.
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.
Custom URL for client links within the email notifications. By default links will be based on “https://matrix.to”.
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.
The number of events to cache in memory. Not affected by caches.global_factor. Defaults to 10K.
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.
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”.
URI to TURN server, can be provided multiple times if there is more than one server.
Shared secret used to access the TURN REST API.
Lifetime of TURN credentials. Defaults to 1h.
Maximum size for user-uploaded files. Defaults to 10M.
Message rate-limiting (per second). Defaults to 0.17.
Message rate-limiting (burst). Defaults to 3.
Login rate-limiting (per-second). Defaults to 0.17.
Login rate-limiting (burst). Defaults to 3.
Only allow email addresses matching specified filter. Can be specified multiple times. A pattern must look like .*@vector.im.
Room where newly-registered users are automatically added. Can be specified multiple times.
Path (on remote) of an application service configuration file to load. Can be specified multiple times.
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.
The worker that is used to run background tasks (e.g. cleaning up expired data). If not provided this defaults to the main process.
Worker to be used for sending federation requests. Can be specified multiple times. Disables sending outbound federation requests from the master process.
If set, allows registration of standard or admin accounts by anyone who has the shared secret, even if registration is otherwise disabled.
Address used to bind the synapse listeners. Can be specified multiple times. Defaults to ‘::1’ and ‘127.0.0.1’.
Arbitrary string to be added to the configuration file. Can be specified multiple times.
Enables user registration on the homeserver.
Enables ldap-backed authentication.
Use STARTTLS when connection to the LDAP server.
Whether or not to report anonymized homeserver usage statistics.
Expose metrics endpoint for Prometheus.
Enable mail notifications (see smtp-* optinal parameters).
Use STARTTLS when connection to the SMTP server.
Disable federation to the broader matrix network.
Make email a required field on registration.
Allow other homeservers to fetch this server’s public room directory.
If set to ‘false’, requires authentication to access the server’s public rooms directory through the client API.
Enable the server notices room.
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.
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 tracking on this homeserver.
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.
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.
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.
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:
limit-remote-room-complexity and remote-room-complexity-threshold
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:
__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.
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.