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
See the folder system for the systemd unit files.
The folder workers
contains an example configuration for the
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 # The replication listener on the main synapse process. worker_replication_host: 127.0.0.1 worker_replication_http_port: 9093 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
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
*.service files accordingly.
There is no need for a separate configuration file for the master process.
- Adjust synapse configuration files as above.
- Copy the
*.targetfiles in system to
systemctl daemon-reloadto tell systemd to load the new unit files.
systemctl enable matrix-synapse.service. This will configure the synapse master process to be started as part of the
- 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.
- Start all the synapse processes with
systemctl start matrix-synapse.target.
- Tell systemd to start synapse on boot with
systemctl enable matrix-synapse.target.
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
Optional: If further hardening is desired, the file
override-hardened.conf may be copied from
in this repository to the location
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
(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.