forked from MirrorHub/synapse
c141455049
Our documentation has a history of using a document's name as a way to link to it, such as "See [workers.md]() for details". This makes sense when you're traversing a directory of files, but less sense when the files are abstracted away - as they are on the documentation website. This PR changes the links to various documentation pages to something that fits better into the surrounding sentence, as you would when making any hyperlink on the web.
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# 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](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
|
|
for the systemd unit files.
|
|
|
|
The folder [workers](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/)
|
|
contains an example configuration for the `federation_reader` worker.
|
|
|
|
## Synapse configuration files
|
|
|
|
See [the worker documentation](../workers.md) for information on how to set up the
|
|
configuration files and reverse-proxy correctly.
|
|
Below is a sample `federation_reader` worker configuration file.
|
|
```yaml
|
|
{{#include workers/federation_reader.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.
|
|
1. Copy the `*.service` and `*.target` files in [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
|
|
to `/etc/systemd/system`.
|
|
1. Run `systemctl daemon-reload` to tell systemd to load the new unit files.
|
|
1. Run `systemctl enable matrix-synapse.service`. This will configure the
|
|
synapse master process to be started as part of the `matrix-synapse.target`
|
|
target.
|
|
1. 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`.
|
|
1. Start all the synapse processes with `systemctl start matrix-synapse.target`.
|
|
1. 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:
|
|
|
|
```sh
|
|
# 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. federation_reader); the master is
|
|
# unaffected by this.
|
|
systemctl restart matrix-synapse-worker@federation_reader.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](https://github.com/matrix-org/synapse/tree/develop/contrib/systemd/)
|
|
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.
|
|
|
|
```sh
|
|
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.
|