2021-07-07 03:44:14 -06:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Systemd - Synapse< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "../favicon.svg" >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "../highlight.css" >
< link rel = "stylesheet" href = "../tomorrow-night.css" >
< link rel = "stylesheet" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< link rel = "stylesheet" href = "../docs/website_files/table-of-contents.css" >
< link rel = "stylesheet" href = "../docs/website_files/remove-nav-buttons.css" >
< link rel = "stylesheet" href = "../docs/website_files/indent-section-headers.css" >
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2023-01-31 11:36:56 -07:00
< ol class = "chapter" > < li class = "chapter-item expanded affix " > < li class = "part-title" > Introduction< / li > < li class = "chapter-item expanded " > < a href = "../welcome_and_overview.html" > Welcome and Overview< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Setup< / li > < li class = "chapter-item expanded " > < a href = "../setup/installation.html" > Installation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../postgres.html" > Using Postgres< / a > < / li > < li class = "chapter-item expanded " > < a href = "../reverse_proxy.html" > Configuring a Reverse Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../setup/forward_proxy.html" > Configuring a Forward/Outbound Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../turn-howto.html" > Configuring a Turn Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../setup/turn/coturn.html" > coturn TURN server< / a > < / li > < li class = "chapter-item expanded " > < a href = "../setup/turn/eturnal.html" > eturnal TURN server< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../delegate.html" > Delegation< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Upgrading< / li > < li class = "chapter-item expanded " > < a href = "../upgrade.html" > Upgrading between Synapse Versions< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Usage< / li > < li class = "chapter-item expanded " > < a href = "../federate.html" > Federation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/index.html" > Configuration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../usage/configuration/config_documentation.html" > Configuration Manual< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/homeserver_sample_config.html" > Homeserver Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/logging_sample_config.html" > Logging Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../structured_logging.html" > Structured Logging< / a > < / li > < li class = "chapter-item expanded " > < a href = "../templates.html" > Templates< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/index.html" > User Authentication< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/index.html" > Single-Sign On< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../openid.html" > OpenID Connect< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/saml.html" > SAML< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/cas.html" > CAS< / a > < / li > < li class = "chapter-item expanded " > < a href = "../sso_mapping_providers.html" > SSO Mapping Providers< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../password_auth_providers.html" > Password Auth Providers< / a > < / li > < li class = "chapter-item expanded " > < a href = "../jwt.html" > JSON Web Tokens< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/refresh_tokens.html" > Refresh Tokens< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../CAPTCHA_SETUP.html" > Registration Captcha< / a > < / li > < li class = "chapter-item expanded " > < a href = "../application_services.html" > Application Services< / a > < / li > < li class = "chapter-item expanded " > < a href = "../server_notices.html" > Server Notices< / a > < / li > < li class = "chapter-item expanded " > < a href = "../consent_tracking.html" > Consent Tracking< / a > < / li > < li class = "chapter-item expanded " > < a href = "../user_directory.html" > User Directory< / a > < / li > < li class = "chapter-item expanded " > < a href = "../message_retention_policies.html" > Message Retention Policies< / a > < / li > < li class = "chapter-item expanded " > < a href = "../modules/index.html" > Pluggable Modules< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../modules/writing_a_module.html" > Writing a module< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded "
2021-07-07 03:44:14 -06:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
< / div >
< h1 class = "menu-title" > Synapse< / h1 >
< div class = "right-buttons" >
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse/edit/develop/docs/systemd-with-workers/README.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- Page table of contents -->
< div class = "sidetoc" >
< nav class = "pagetoc" > < / nav >
< / div >
< h1 id = "setting-up-synapse-with-workers-and-systemd" > < a class = "header" href = "#setting-up-synapse-with-workers-and-systemd" > Setting up Synapse with Workers and Systemd< / a > < / h1 >
< p > This is a setup for managing synapse with systemd, including support for
managing workers. It provides a < code > matrix-synapse< / code > service for the master, as
well as a < code > matrix-synapse-worker@< / code > service template for any workers you
require. Additionally, to group the required services, it sets up a
< code > matrix-synapse.target< / code > .< / p >
< p > See the folder < a href = "https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/" > system< / a >
for the systemd unit files.< / p >
< p > The folder < a href = "https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/" > workers< / a >
2022-05-03 04:52:17 -06:00
contains an example configuration for the < code > generic_worker< / code > worker.< / p >
2021-07-07 03:44:14 -06:00
< h2 id = "synapse-configuration-files" > < a class = "header" href = "#synapse-configuration-files" > Synapse configuration files< / a > < / h2 >
2021-07-29 04:09:19 -06:00
< p > See < a href = "../workers.html" > the worker documentation< / a > for information on how to set up the
configuration files and reverse-proxy correctly.
2022-05-03 04:52:17 -06:00
Below is a sample < code > generic_worker< / code > worker configuration file.< / p >
< pre > < code class = "language-yaml" > worker_app: synapse.app.generic_worker
worker_name: generic_worker1
2021-07-29 04:09:19 -06:00
2022-05-03 04:52:17 -06:00
# The replication listener on the main synapse process.
2021-07-29 04:09:19 -06:00
worker_replication_host: 127.0.0.1
worker_replication_http_port: 9093
worker_listeners:
2022-05-03 04:52:17 -06:00
- type: http
port: 8083
2023-01-31 11:36:56 -07:00
x_forwarded: true
2022-05-03 04:52:17 -06:00
resources:
- names: [client, federation]
2021-07-29 04:09:19 -06:00
2022-05-03 04:52:17 -06:00
worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
2021-07-29 04:09:19 -06:00
< / code > < / pre >
2021-07-07 03:44:14 -06:00
< p > Systemd manages daemonization itself, so ensure that none of the configuration
files set either < code > daemonize< / code > or < code > worker_daemonize< / code > .< / p >
< p > The config files of all workers are expected to be located in
< code > /etc/matrix-synapse/workers< / code > . If you want to use a different location, edit
the provided < code > *.service< / code > files accordingly.< / p >
< p > There is no need for a separate configuration file for the master process.< / p >
< h2 id = "set-up" > < a class = "header" href = "#set-up" > Set up< / a > < / h2 >
< ol >
< li > Adjust synapse configuration files as above.< / li >
< li > Copy the < code > *.service< / code > and < code > *.target< / code > files in < a href = "https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/" > system< / a >
to < code > /etc/systemd/system< / code > .< / li >
< li > Run < code > systemctl daemon-reload< / code > to tell systemd to load the new unit files.< / li >
< li > Run < code > systemctl enable matrix-synapse.service< / code > . This will configure the
synapse master process to be started as part of the < code > matrix-synapse.target< / code >
target.< / li >
< li > For each worker process to be enabled, run < code > systemctl enable matrix-synapse-worker@< worker_name> .service< / code > . For each < code > < worker_name> < / code > , there
should be a corresponding configuration file.
< code > /etc/matrix-synapse/workers/< worker_name> .yaml< / code > .< / li >
< li > Start all the synapse processes with < code > systemctl start matrix-synapse.target< / code > .< / li >
< li > Tell systemd to start synapse on boot with < code > systemctl enable matrix-synapse.target< / code > .< / li >
< / ol >
< h2 id = "usage" > < a class = "header" href = "#usage" > Usage< / a > < / h2 >
< p > Once the services are correctly set up, you can use the following commands
to manage your synapse installation:< / p >
< pre > < code class = "language-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
2022-05-03 04:52:17 -06:00
# Restart a specific worker (eg. generic_worker); the master is
2021-07-07 03:44:14 -06:00
# unaffected by this.
2022-05-03 04:52:17 -06:00
systemctl restart matrix-synapse-worker@generic_worker.service
2021-07-07 03:44:14 -06:00
# Add a new worker (assuming all configs are set up already)
systemctl enable matrix-synapse-worker@federation_writer.service
systemctl restart matrix-synapse.target
< / code > < / pre >
< h2 id = "hardening" > < a class = "header" href = "#hardening" > Hardening< / a > < / h2 >
< p > < strong > Optional:< / strong > If further hardening is desired, the file
< code > override-hardened.conf< / code > may be copied from
2021-07-29 04:09:19 -06:00
< a href = "https://github.com/matrix-org/synapse/tree/develop/contrib/systemd/" > contrib/systemd/override-hardened.conf< / a >
in this repository to the location
2021-07-07 03:44:14 -06:00
< code > /etc/systemd/system/matrix-synapse.service.d/override-hardened.conf< / code > (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
2021-07-29 04:09:19 -06:00
understand what the override file is doing. The same file will need to be copied to
2021-07-07 03:44:14 -06:00
< code > /etc/systemd/system/matrix-synapse-worker@.service.d/override-hardened-worker.conf< / code >
(this directory may also have to be created) in order to apply the same
hardening options to any worker processes.< / p >
< p > 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.< / p >
< pre > < code class = "language-sh" > systemctl daemon-reload
# Restart services
systemctl restart matrix-synapse.target
< / code > < / pre >
< p > In order to see their effect, you may run < code > systemd-analyze security matrix-synapse.service< / code > before and after applying the hardening options to see
the changes being applied at a glance.< / p >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../synctl_workers.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../usage/administration/index.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "../synctl_workers.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../usage/administration/index.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "../elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" src = "../docs/website_files/table-of-contents.js" > < / script >
< / body >
< / html >
