Setting up Synapse with Workers and Systemd

This is a setup for managing synapse with systemd, including support for managing workers. It provides a matrix-synapse service for the master, as well as a matrix-synapse-worker@ service template for any workers you require. Additionally, to group the required services, it sets up a matrix-synapse.target.

See the folder system for the systemd unit files.

The folder workers contains an example configuration for the generic_worker worker.

Synapse configuration files

See the worker documentation for information on how to set up the configuration files and reverse-proxy correctly. Below is a sample generic_worker worker configuration file.

worker_app: synapse.app.generic_worker
worker_name: generic_worker1

worker_listeners:
  - type: http
    port: 8083
    x_forwarded: true
    resources:
      - names: [client, federation]

worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml

Systemd manages daemonization itself, so ensure that none of the configuration files set either daemonize or worker_daemonize.

The config files of all workers are expected to be located in /etc/matrix-synapse/workers. If you want to use a different location, edit the provided *.service files accordingly.

There is no need for a separate configuration file for the master process.

Set up

1. Adjust synapse configuration files as above.
2. Copy the *.service and *.target files in system to /etc/systemd/system.
3. Run systemctl daemon-reload to tell systemd to load the new unit files.
4. Run systemctl enable matrix-synapse.service. This will configure the synapse master process to be started as part of the matrix-synapse.target target.
5. For each worker process to be enabled, run systemctl enable matrix-synapse-worker@<worker_name>.service. For each <worker_name>, there should be a corresponding configuration file. /etc/matrix-synapse/workers/<worker_name>.yaml.
6. Start all the synapse processes with systemctl start matrix-synapse.target.
7. Tell systemd to start synapse on boot with systemctl enable matrix-synapse.target.

Usage

Once the services are correctly set up, you can use the following commands to manage your synapse installation:

# Restart Synapse master and all workers
systemctl restart matrix-synapse.target

# Stop Synapse and all workers
systemctl stop matrix-synapse.target

# Restart the master alone
systemctl start matrix-synapse.service

# Restart a specific worker (eg. generic_worker); the master is
# unaffected by this.
systemctl restart matrix-synapse-worker@generic_worker.service

# Add a new worker (assuming all configs are set up already)
systemctl enable matrix-synapse-worker@federation_writer.service
systemctl restart matrix-synapse.target

Hardening

Optional: If further hardening is desired, the file override-hardened.conf may be copied from contrib/systemd/override-hardened.conf in this repository to the location /etc/systemd/system/matrix-synapse.service.d/override-hardened.conf (the directory may have to be created). It enables certain sandboxing features in systemd to further secure the synapse service. You may read the comments to understand what the override file is doing. The same file will need to be copied to /etc/systemd/system/matrix-synapse-worker@.service.d/override-hardened-worker.conf (this directory may also have to be created) in order to apply the same hardening options to any worker processes.

Once these files have been copied to their appropriate locations, simply reload systemd's manager config files and restart all Synapse services to apply the hardening options. They will automatically be applied at every restart as long as the override files are present at the specified locations.

systemctl daemon-reload

# Restart services
systemctl restart matrix-synapse.target

In order to see their effect, you may run systemd-analyze security matrix-synapse.service before and after applying the hardening options to see the changes being applied at a glance.