Fediversity/matrix/synapse/README.md

363 lines
9.9 KiB
Markdown
Raw Normal View History

2024-11-04 15:03:22 +01:00
---
gitea: none
include_toc: true
---
# Installation and configuration of Synapse
Mind you: this an installation on Debian Linux (at least for now).
Start by installing the latest Synapse server, see the [upstream
documentation](https://element-hq.github.io/synapse/latest/setup/installation.html).
```
apt install -y lsb-release wget apt-transport-https build-essential python3-dev libffi-dev \
python3-pip python3-setuptools sqlite3 \
libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-dev
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
tee /etc/apt/sources.list.d/matrix-org.list
apt update
apt install matrix-synapse-py3
```
This leaves a very basic configuration in `/etc/matrix-synapse/homeserver.yaml`
and two settings under `/etc/conf.d`. All other configuration items will also
be configured with yaml-files in this directory.
Configure the domain you with to use in `/etc/matrix-synapse/conf.d/server_name.yaml`.
What you configure here will also be the global part of your Matrix handles
(the part after the colon). Also add the URL clients should connect to:
```
server_name: example.com
public_baseurl: https://matrix.example.com/
```
The `public_baseurl` will probably be different than the `server_name`, see
2024-11-14 11:42:08 +01:00
also [Delegation and DNS](#Delegation).
You now have a standard Matrix server that uses sqlite. You really don't want
to use this in production, so probably want to replace this with PostgreSQL.
There are two different ways to configure Synapse, documented here:
2024-11-04 15:03:22 +01:00
* [Monolithic](monolithic)
* [Workers](workers)
We'll use Synapse, using the workers architecture to make it scalable, flexible and reusable.
2024-11-04 15:18:52 +01:00
2024-11-12 15:38:05 +01:00
# Listeners
2024-11-12 15:38:05 +01:00
A fresh installation configures one listener, for both client and federation
traffic. This listens on port 8008 on localhost (IPv4 and IPv6) and does not
do TLS:
```
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['::1', '127.0.0.1']
resources:
- names: [client, federation]
compress: false
```
# Database
2024-11-04 15:18:52 +01:00
2024-11-04 15:25:28 +01:00
The default installation leaves you with an sqlite3 database. Nice for experimenting, but
unsuitable for a production environment.
2024-11-04 15:27:00 +01:00
[Here's how you setup PostgreSQL](../postgresql).
2024-11-04 15:25:28 +01:00
2024-11-04 17:18:18 +01:00
Once you've created a database and user in PostgreSQL, you configure Synapse
to use it.
First delete (or comment out) the SQLITE datbase in `homeserver.yaml`:
```
#database:
# name: sqlite3
# args:
# database: /var/lib/matrix-synapse/homeserver.db
```
Then create the database configuration for PostgreSQL in
`conf.d/database.yaml`:
```
database:
name: psycopg2
args:
user: synapse
password: <password>
dbname: synapse
host: /var/run/postgresql
cp_min: 5
cp_max: 10
```
Note: you configure the directory where the UNIX socket file lives, not the
actual file.
Of course, if you use localhost, you should configure it like this:
```
host: localhost
port: 5432
```
After changing the database, restart Synapse and check whether it can connect
and create the tables it needs.
2024-11-04 15:25:28 +01:00
# Create admin
Synapse doesn't create an admin account at install time, so you'll have to do
that yourself.
You need to set a `registration_shared_secret` for this, set that in
`conf.d/keys.yaml` like this:
```
registration_shared_secret: xxxx
```
You can create such a key by running `pwgen -csn 52 1`. Restart Synapse after
setting this key.
Now create an admin user. Login and issue this command:
```
register_new_matrix_user -u admin -a -c /etc/matrix-synapse/conf.d/keys.yaml
```
This will ask for a password, choose a safe one.
# Logging
2024-11-04 15:18:52 +01:00
Logging is configured in `log.yaml`. Some logging should go to systemd, the
more specific logging to Synapse's own logfile(s).
This part is yet to be completed.
2024-11-04 15:18:52 +01:00
# Delegation and DNS {#Delegation}
2024-11-13 17:00:39 +01:00
If you run your server under a different FQDN than just the domain name you
want to use, you need to delegate: point from your domain to the server.
Example. You want to use example.com for your domain, but your server is
called matrix.example.com. To make that work, you need to serve 2 bits of
2024-11-13 17:22:35 +01:00
JSON-code on example.com to point clients and servers to the correct
2024-11-13 17:00:39 +01:00
machine: matrix.example.com.
Pointing servers to the correct server is done by publishing this bit of
JSON-code under `https://example.com/.well-known/matrix/server`:
```
{
"m.homeserver": {"base_url": "https://matrix.example.com"},
"org.matrix.msc3575.proxy": {"url": "https://matrix.example.com"}
}
```
Pointing clients to the correct server needs this at
`https://example.com/.well-known/matrix/client`:
```
{
"m.server": "matrix.example.com"
}
```
Very important: both names (example.com and matrix.example.com) must be A
and/or AAAA records in DNS, not CNAME.
See [nginx](../nginx) for details about how to publish this data.
2024-11-14 11:55:08 +01:00
# Blacklists
2024-11-14 11:55:08 +01:00
You don't want Synapse to try to contact certain IP-addresses, especially not
those that are unroutable or for special uses. Add these addresses to `ip_range_blacklist`,
in `conf.d/ip_range_blacklist.yaml`:
```
ip_range_blacklist:
- '127.0.0.0/8'
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/16'
- '100.64.0.0/10'
- '192.0.0.0/24'
- '169.254.0.0/16'
- '192.88.99.0/24'
- '198.18.0.0/15'
- '192.0.2.0/24'
- '198.51.100.0/24'
- '203.0.113.0/24'
- '224.0.0.0/4'
- '::1/128'
- 'fe80::/10'
- 'fc00::/7'
- '2001:db8::/32'
- 'ff00::/8'
- 'fec0::/10'
```
You want to add addresses of malicious or otherwise unwanted machines to this
list too. See [Synapse's documentation](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html?highlight=ip_range_blacklist#ip_range_blacklist)
for more information.
2024-11-14 13:48:30 +01:00
# E-mail {#Email}
Synapse should probably be able to send out e-mails; notifications for those
who want that, and password reset for those who need one.
You configure this under the section `email` (yes, really).
First of all, you need an SMTP-server that is configured to send e-mail for
your domain. Configuring that is out of scope, we'll assume we can use the
server `smtp.example.com`.
Configure this in `conf.d/email.yaml`:
```
email:
smtp_host: smtp.example.com
smtp_port: 465
smtp_user: matrix@example.com
smtp_pass: SuperSecretPassword
force_tls: true
notif_from: "Your Matrix server <matrix@example.com>"
```
This configures an SMTP-connection with SSL (port 465, `force_tls`). See Matrix'
[email documentation](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html?highlight=require_transport_security#email)
for more information.
# Media store {#mediastore}
Files and avatars need to be stored somewhere, we configure these options in
`conf.d/mediastore.yaml`:
```
media_store_path: /var/lib/matrix-synapse/media
enable_authenticated_media: true
max_upload_size: 50M
url_preview_enabled: true
url_preview_ip_range_blacklist:
- '127.0.0.0/8'
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/16'
- '100.64.0.0/10'
- '192.0.0.0/24'
- '169.254.0.0/16'
- '192.88.99.0/24'
- '198.18.0.0/15'
- '192.0.2.0/24'
- '198.51.100.0/24'
- '203.0.113.0/24'
- '224.0.0.0/4'
- '::1/128'
- 'fe80::/10'
- 'fc00::/7'
- '2001:db8::/32'
- 'ff00::/8'
- 'fec0::/10'
```
These are a few sane (?) defaults, check [Matrix' documentation](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html?highlight=media_store_path#media-store)
for many more options.
# Homeserver blocking {#blocking}
This is a series of options that can be used to block and/or limit users. The
whole list of options can be found in [Matrix' documentation](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html?highlight=mau_stats_only%3A#homeserver-blocking),
we're going to pick out a few useful ones.
Let's configure these options in `conf.d/homeserver_blocking.yaml`.
```
admin_contact: matrixadmin@example.com
mau_stats_only: true
max_avatar_size: 2M
allowed_avatar_mimetypes:
- "image/png"
- "image/jpeg"
- "image/gif"
forgotten_room_retention_period: 7d
```
2024-11-14 16:51:12 +01:00
# Signon
Logging in can be done in basically two ways: an internal or external
database. Let's start with the first: users and their passwords are stored in
Synapse's database.
We use `conf.d/signon.yaml` to configure this stuff.
```
password_config:
policy:
enabled: true
localdb_enabled: true
pepper: CxDC6jU5FAxAcvD
minimum_length: 8
require_digit: true
require_symbol: true
require_lowercase: true
require_uppercase: true
```
With this bit, we configure Synapse to let users pick and change their own
passwords, as long as they meet the configured conditions. Mind you: `pepper` is
a secret random string that should *NEVER* be changed after initial setup.
But in a bigger environment you'll probably want to use some authentication
backend, such as LDAP. LDAP is configured by means of a module (see
[Synapse LDAP auth Provider](https://github.com/matrix-org/matrix-synapse-ldap3/)
on Github).
Configuring Synapse to use LDAP, would be something like this:
```
password_config:
policy:
enabled: only_for_reauth
localdb_enabled: false
password_providers:
- module: "ldap_auth_provider.LdapAuthProvider"
config:
enabled: true
uri: "ldap://ldap.example.com:389"
start_tls: true
base: "ou=users,o=Example,dc=example,dc=com"
attributes:
uid: "uid"
mail: "email"
name: "givenName"
filter: "(&(objectClass=posixAccount)(accountStatus=active))"
```
This would connect to ldap.example.com over TLS, and authenticate users that
live under `ou=users,o=Example,dc=example,dc=com` and that are active Posix
accounts. Users will not be able to change their passwords via Matrix, they
have to do that in LDAP.
(this setup has not been tested, although it borrows heavily from the current
ProcoliX setup).