ungleich-public/cdist-contrib
ungleich-public
/
cdist-contrib
7
2
Fork 3
Code Issues 5 Pull Requests 5 Projects Releases Wiki Activity
cdist-contrib/type/__matrix_synapse/man.rst

361 lines
12 KiB
ReStructuredText
Raw Blame History

cdist-type__matrix_synapse(7)
======================
NAME
----
cdist-type__matrix_synapse - Install and configure Synapse, a Matrix homeserver
DESCRIPTION
-----------
This type install and configure 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 attriute mapping to Synapse's uid field, default to uid.
ldap-mail-attribute
LDAP attriute mapping to Synapse's mail field, default to mail.
ldap-name-attribute
LDAP attriute 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`.
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)
<cdist-type__matrix_synapse_worker.html>`_ type to set up workers when the
worker-mode flag is set.
Worker mode depend on the following components:
* A working `redis <https://redis.io/>`_ server
* The hiredis python package (`python3-hiredis
<https://packages.debian.org/buster/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)
<cdist-type__python_pip.html>`_ core cdist type).
It is also recommended to first take a look at:
- `upstream's high-level overview on workers (matrix.org blog post) <https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability>`_
- `upstream's documentation on workers <https://github.com/matrix-org/synapse/blob/develop/docs/workers.md>`_
EXAMPLES
--------
.. code-block:: sh
__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
<https://code.ungleich.ch/ungleich-public/cdist-ungleich/-/tree/master/type/__ungleich_matrix>`_
meta-type.
SEE ALSO
--------
- `cdist-type__matrix_element(7) <cdist-type__matrix_element.html>`_
- `cdist-type__matrix_synapse_admin(7) <cdist-type__matrix_synapse_admin.html>`_
- `cdist-type__matrix_synapse_worker(7) <cdist-type__matrix_synapse_worker.html>`_
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.
Reference in New Issue View Git Blame Copy Permalink