workers.html 52 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755
  1. <!DOCTYPE HTML>
  2. <html lang="en" class="sidebar-visible no-js light">
  3. <head>
  4. <!-- Book generated using mdBook -->
  5. <meta charset="UTF-8">
  6. <title>Workers - Synapse</title>
  7. <!-- Custom HTML head -->
  8. <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  9. <meta name="description" content="">
  10. <meta name="viewport" content="width=device-width, initial-scale=1">
  11. <meta name="theme-color" content="#ffffff" />
  12. <link rel="icon" href="favicon.svg">
  13. <link rel="shortcut icon" href="favicon.png">
  14. <link rel="stylesheet" href="css/variables.css">
  15. <link rel="stylesheet" href="css/general.css">
  16. <link rel="stylesheet" href="css/chrome.css">
  17. <link rel="stylesheet" href="css/print.css" media="print">
  18. <!-- Fonts -->
  19. <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
  20. <link rel="stylesheet" href="fonts/fonts.css">
  21. <!-- Highlight.js Stylesheets -->
  22. <link rel="stylesheet" href="highlight.css">
  23. <link rel="stylesheet" href="tomorrow-night.css">
  24. <link rel="stylesheet" href="ayu-highlight.css">
  25. <!-- Custom theme stylesheets -->
  26. <link rel="stylesheet" href="docs/website_files/table-of-contents.css">
  27. <link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css">
  28. <link rel="stylesheet" href="docs/website_files/indent-section-headers.css">
  29. <link rel="stylesheet" href="docs/website_files/version-picker.css">
  30. </head>
  31. <body>
  32. <!-- Provide site root to javascript -->
  33. <script type="text/javascript">
  34. var path_to_root = "";
  35. var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
  36. </script>
  37. <!-- Work around some values being stored in localStorage wrapped in quotes -->
  38. <script type="text/javascript">
  39. try {
  40. var theme = localStorage.getItem('mdbook-theme');
  41. var sidebar = localStorage.getItem('mdbook-sidebar');
  42. if (theme.startsWith('"') && theme.endsWith('"')) {
  43. localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
  44. }
  45. if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
  46. localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
  47. }
  48. } catch (e) { }
  49. </script>
  50. <!-- Set the theme before any content is loaded, prevents flash -->
  51. <script type="text/javascript">
  52. var theme;
  53. try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
  54. if (theme === null || theme === undefined) { theme = default_theme; }
  55. var html = document.querySelector('html');
  56. html.classList.remove('no-js')
  57. html.classList.remove('light')
  58. html.classList.add(theme);
  59. html.classList.add('js');
  60. </script>
  61. <!-- Hide / unhide sidebar before it is displayed -->
  62. <script type="text/javascript">
  63. var html = document.querySelector('html');
  64. var sidebar = 'hidden';
  65. if (document.body.clientWidth >= 1080) {
  66. try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
  67. sidebar = sidebar || 'visible';
  68. }
  69. html.classList.remove('sidebar-visible');
  70. html.classList.add("sidebar-" + sidebar);
  71. </script>
  72. <nav id="sidebar" class="sidebar" aria-label="Table of contents">
  73. <div class="sidebar-scrollbox">
  74. <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 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="development/url_previews.html">URL Previews</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 "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_data_callbacks.html">Account data callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html" class="active">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/background_updates.html">Background Updates</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/federation.html">Federation</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li class="chapter-item expanded "><a href="usage/administration/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_faq.html">Admin FAQ</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/releases.html">Release Cycle</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/demo.html">Demo scripts</a></li></ol></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><a href="development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/synapse_architecture/cancellation.html">Cancellation</a></li><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li><li class="chapter-item expanded "><a href="other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</a></li></ol>
  75. </div>
  76. <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
  77. </nav>
  78. <div id="page-wrapper" class="page-wrapper">
  79. <div class="page">
  80. <div id="menu-bar-hover-placeholder"></div>
  81. <div id="menu-bar" class="menu-bar sticky bordered">
  82. <div class="left-buttons">
  83. <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
  84. <i class="fa fa-bars"></i>
  85. </button>
  86. <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">
  87. <i class="fa fa-paint-brush"></i>
  88. </button>
  89. <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
  90. <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
  91. <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
  92. <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
  93. <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
  94. <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
  95. </ul>
  96. <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">
  97. <i class="fa fa-search"></i>
  98. </button>
  99. <div class="version-picker">
  100. <div class="dropdown">
  101. <div class="select">
  102. <span></span>
  103. <i class="fa fa-chevron-down"></i>
  104. </div>
  105. <input type="hidden" name="version">
  106. <ul class="dropdown-menu">
  107. <!-- Versions will be added dynamically in version-picker.js -->
  108. </ul>
  109. </div>
  110. </div>
  111. </div>
  112. <h1 class="menu-title">Synapse</h1>
  113. <div class="right-buttons">
  114. <a href="print.html" title="Print this book" aria-label="Print this book">
  115. <i id="print-button" class="fa fa-print"></i>
  116. </a>
  117. <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
  118. <i id="git-repository-button" class="fa fa-github"></i>
  119. </a>
  120. <a href="https://github.com/matrix-org/synapse/edit/develop/docs/workers.md" title="Suggest an edit" aria-label="Suggest an edit">
  121. <i id="git-edit-button" class="fa fa-edit"></i>
  122. </a>
  123. </div>
  124. </div>
  125. <div id="search-wrapper" class="hidden">
  126. <form id="searchbar-outer" class="searchbar-outer">
  127. <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
  128. </form>
  129. <div id="searchresults-outer" class="searchresults-outer hidden">
  130. <div id="searchresults-header" class="searchresults-header"></div>
  131. <ul id="searchresults">
  132. </ul>
  133. </div>
  134. </div>
  135. <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
  136. <script type="text/javascript">
  137. document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
  138. document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
  139. Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
  140. link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
  141. });
  142. </script>
  143. <div id="content" class="content">
  144. <main>
  145. <!-- Page table of contents -->
  146. <div class="sidetoc">
  147. <nav class="pagetoc"></nav>
  148. </div>
  149. <h1 id="scaling-synapse-via-workers"><a class="header" href="#scaling-synapse-via-workers">Scaling synapse via workers</a></h1>
  150. <p>For small instances it is recommended to run Synapse in the default monolith mode.
  151. For larger instances where performance is a concern it can be helpful to split
  152. out functionality into multiple separate python processes. These processes are
  153. called 'workers', and are (eventually) intended to scale horizontally
  154. independently.</p>
  155. <p>Synapse's worker support is under active development and subject to change as
  156. we attempt to rapidly scale ever larger Synapse instances. However we are
  157. documenting it here to help admins needing a highly scalable Synapse instance
  158. similar to the one running <code>matrix.org</code>.</p>
  159. <p>All processes continue to share the same database instance, and as such,
  160. workers only work with PostgreSQL-based Synapse deployments. SQLite should only
  161. be used for demo purposes and any admin considering workers should already be
  162. running PostgreSQL.</p>
  163. <p>See also <a href="https://matrix.org/blog/2020/11/03/how-we-fixed-synapses-scalability">Matrix.org blog post</a>
  164. for a higher level overview.</p>
  165. <h2 id="main-processworker-communication"><a class="header" href="#main-processworker-communication">Main process/worker communication</a></h2>
  166. <p>The processes communicate with each other via a Synapse-specific protocol called
  167. 'replication' (analogous to MySQL- or Postgres-style database replication) which
  168. feeds streams of newly written data between processes so they can be kept in
  169. sync with the database state.</p>
  170. <p>When configured to do so, Synapse uses a
  171. <a href="https://redis.io/docs/manual/pubsub/">Redis pub/sub channel</a> to send the replication
  172. stream between all configured Synapse processes. Additionally, processes may
  173. make HTTP requests to each other, primarily for operations which need to wait
  174. for a reply ─ such as sending an event.</p>
  175. <p>Redis support was added in v1.13.0 with it becoming the recommended method in
  176. v1.18.0. It replaced the old direct TCP connections (which is deprecated as of
  177. v1.18.0) to the main process. With Redis, rather than all the workers connecting
  178. to the main process, all the workers and the main process connect to Redis,
  179. which relays replication commands between processes. This can give a significant
  180. cpu saving on the main process and will be a prerequisite for upcoming
  181. performance improvements.</p>
  182. <p>If Redis support is enabled Synapse will use it as a shared cache, as well as a
  183. pub/sub mechanism.</p>
  184. <p>See the <a href="#architectural-diagram">Architectural diagram</a> section at the end for
  185. a visualisation of what this looks like.</p>
  186. <h2 id="setting-up-workers"><a class="header" href="#setting-up-workers">Setting up workers</a></h2>
  187. <p>A Redis server is required to manage the communication between the processes.
  188. The Redis server should be installed following the normal procedure for your
  189. distribution (e.g. <code>apt install redis-server</code> on Debian). It is safe to use an
  190. existing Redis deployment if you have one.</p>
  191. <p>Once installed, check that Redis is running and accessible from the host running
  192. Synapse, for example by executing <code>echo PING | nc -q1 localhost 6379</code> and seeing
  193. a response of <code>+PONG</code>.</p>
  194. <p>The appropriate dependencies must also be installed for Synapse. If using a
  195. virtualenv, these can be installed with:</p>
  196. <pre><code class="language-sh">pip install &quot;matrix-synapse[redis]&quot;
  197. </code></pre>
  198. <p>Note that these dependencies are included when synapse is installed with <code>pip install matrix-synapse[all]</code>. They are also included in the debian packages from
  199. <code>matrix.org</code> and in the docker images at
  200. https://hub.docker.com/r/matrixdotorg/synapse/.</p>
  201. <p>To make effective use of the workers, you will need to configure an HTTP
  202. reverse-proxy such as nginx or haproxy, which will direct incoming requests to
  203. the correct worker, or to the main synapse instance. See
  204. <a href="reverse_proxy.html">the reverse proxy documentation</a> for information on setting up a reverse
  205. proxy.</p>
  206. <p>When using workers, each worker process has its own configuration file which
  207. contains settings specific to that worker, such as the HTTP listener that it
  208. provides (if any), logging configuration, etc.</p>
  209. <p>Normally, the worker processes are configured to read from a shared
  210. configuration file as well as the worker-specific configuration files. This
  211. makes it easier to keep common configuration settings synchronised across all
  212. the processes.</p>
  213. <p>The main process is somewhat special in this respect: it does not normally
  214. need its own configuration file and can take all of its configuration from the
  215. shared configuration file.</p>
  216. <h3 id="shared-configuration"><a class="header" href="#shared-configuration">Shared configuration</a></h3>
  217. <p>Normally, only a couple of changes are needed to make an existing configuration
  218. file suitable for use with workers. First, you need to enable an &quot;HTTP replication
  219. listener&quot; for the main process; and secondly, you need to enable redis-based
  220. replication. Optionally, a shared secret can be used to authenticate HTTP
  221. traffic between workers. For example:</p>
  222. <pre><code class="language-yaml"># extend the existing `listeners` section. This defines the ports that the
  223. # main process will listen on.
  224. listeners:
  225. # The HTTP replication port
  226. - port: 9093
  227. bind_address: '127.0.0.1'
  228. type: http
  229. resources:
  230. - names: [replication]
  231. # Add a random shared secret to authenticate traffic.
  232. worker_replication_secret: &quot;&quot;
  233. redis:
  234. enabled: true
  235. </code></pre>
  236. <p>See the sample config for the full documentation of each option.</p>
  237. <p>Under <strong>no circumstances</strong> should the replication listener be exposed to the
  238. public internet; it has no authentication and is unencrypted.</p>
  239. <h3 id="worker-configuration"><a class="header" href="#worker-configuration">Worker configuration</a></h3>
  240. <p>In the config file for each worker, you must specify the type of worker
  241. application (<code>worker_app</code>), and you should specify a unique name for the worker
  242. (<code>worker_name</code>). The currently available worker applications are listed below.
  243. You must also specify the HTTP replication endpoint that it should talk to on
  244. the main synapse process. <code>worker_replication_host</code> should specify the host of
  245. the main synapse and <code>worker_replication_http_port</code> should point to the HTTP
  246. replication port. If the worker will handle HTTP requests then the
  247. <code>worker_listeners</code> option should be set with a <code>http</code> listener, in the same way
  248. as the <code>listeners</code> option in the shared config.</p>
  249. <p>For example:</p>
  250. <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
  251. worker_name: generic_worker1
  252. # The replication listener on the main synapse process.
  253. worker_replication_host: 127.0.0.1
  254. worker_replication_http_port: 9093
  255. worker_listeners:
  256. - type: http
  257. port: 8083
  258. resources:
  259. - names: [client, federation]
  260. worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
  261. </code></pre>
  262. <p>...is a full configuration for a generic worker instance, which will expose a
  263. plain HTTP endpoint on port 8083 separately serving various endpoints, e.g.
  264. <code>/sync</code>, which are listed below.</p>
  265. <p>Obviously you should configure your reverse-proxy to route the relevant
  266. endpoints to the worker (<code>localhost:8083</code> in the above example).</p>
  267. <h3 id="running-synapse-with-workers"><a class="header" href="#running-synapse-with-workers">Running Synapse with workers</a></h3>
  268. <p>Finally, you need to start your worker processes. This can be done with either
  269. <code>synctl</code> or your distribution's preferred service manager such as <code>systemd</code>. We
  270. recommend the use of <code>systemd</code> where available: for information on setting up
  271. <code>systemd</code> to start synapse workers, see
  272. <a href="systemd-with-workers">Systemd with Workers</a>. To use <code>synctl</code>, see
  273. <a href="synctl_workers.html">Using synctl with Workers</a>.</p>
  274. <h2 id="available-worker-applications"><a class="header" href="#available-worker-applications">Available worker applications</a></h2>
  275. <h3 id="synapseappgeneric_worker"><a class="header" href="#synapseappgeneric_worker"><code>synapse.app.generic_worker</code></a></h3>
  276. <p>This worker can handle API requests matching the following regular expressions.
  277. These endpoints can be routed to any worker. If a worker is set up to handle a
  278. stream then, for maximum efficiency, additional endpoints should be routed to that
  279. worker: refer to the <a href="#stream-writers">stream writers</a> section below for further
  280. information.</p>
  281. <pre><code># Sync requests
  282. ^/_matrix/client/(r0|v3)/sync$
  283. ^/_matrix/client/(api/v1|r0|v3)/events$
  284. ^/_matrix/client/(api/v1|r0|v3)/initialSync$
  285. ^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$
  286. # Federation requests
  287. ^/_matrix/federation/v1/event/
  288. ^/_matrix/federation/v1/state/
  289. ^/_matrix/federation/v1/state_ids/
  290. ^/_matrix/federation/v1/backfill/
  291. ^/_matrix/federation/v1/get_missing_events/
  292. ^/_matrix/federation/v1/publicRooms
  293. ^/_matrix/federation/v1/query/
  294. ^/_matrix/federation/v1/make_join/
  295. ^/_matrix/federation/v1/make_leave/
  296. ^/_matrix/federation/(v1|v2)/send_join/
  297. ^/_matrix/federation/(v1|v2)/send_leave/
  298. ^/_matrix/federation/(v1|v2)/invite/
  299. ^/_matrix/federation/v1/event_auth/
  300. ^/_matrix/federation/v1/exchange_third_party_invite/
  301. ^/_matrix/federation/v1/user/devices/
  302. ^/_matrix/key/v2/query
  303. ^/_matrix/federation/v1/hierarchy/
  304. # Inbound federation transaction request
  305. ^/_matrix/federation/v1/send/
  306. # Client API requests
  307. ^/_matrix/client/(api/v1|r0|v3|unstable)/createRoom$
  308. ^/_matrix/client/(api/v1|r0|v3|unstable)/publicRooms$
  309. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/joined_members$
  310. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/context/.*$
  311. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/members$
  312. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state$
  313. ^/_matrix/client/v1/rooms/.*/hierarchy$
  314. ^/_matrix/client/unstable/org.matrix.msc2716/rooms/.*/batch_send$
  315. ^/_matrix/client/unstable/im.nheko.summary/rooms/.*/summary$
  316. ^/_matrix/client/(r0|v3|unstable)/account/3pid$
  317. ^/_matrix/client/(r0|v3|unstable)/account/whoami$
  318. ^/_matrix/client/(r0|v3|unstable)/devices$
  319. ^/_matrix/client/versions$
  320. ^/_matrix/client/(api/v1|r0|v3|unstable)/voip/turnServer$
  321. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/event/
  322. ^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
  323. ^/_matrix/client/(api/v1|r0|v3|unstable)/search$
  324. # Encryption requests
  325. ^/_matrix/client/(r0|v3|unstable)/keys/query$
  326. ^/_matrix/client/(r0|v3|unstable)/keys/changes$
  327. ^/_matrix/client/(r0|v3|unstable)/keys/claim$
  328. ^/_matrix/client/(r0|v3|unstable)/room_keys/
  329. # Registration/login requests
  330. ^/_matrix/client/(api/v1|r0|v3|unstable)/login$
  331. ^/_matrix/client/(r0|v3|unstable)/register$
  332. ^/_matrix/client/v1/register/m.login.registration_token/validity$
  333. # Event sending requests
  334. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/redact
  335. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/send
  336. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state/
  337. ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
  338. ^/_matrix/client/(api/v1|r0|v3|unstable)/join/
  339. ^/_matrix/client/(api/v1|r0|v3|unstable)/profile/
  340. # Account data requests
  341. ^/_matrix/client/(r0|v3|unstable)/.*/tags
  342. ^/_matrix/client/(r0|v3|unstable)/.*/account_data
  343. # Receipts requests
  344. ^/_matrix/client/(r0|v3|unstable)/rooms/.*/receipt
  345. ^/_matrix/client/(r0|v3|unstable)/rooms/.*/read_markers
  346. # Presence requests
  347. ^/_matrix/client/(api/v1|r0|v3|unstable)/presence/
  348. # User directory search requests
  349. ^/_matrix/client/(r0|v3|unstable)/user_directory/search$
  350. </code></pre>
  351. <p>Additionally, the following REST endpoints can be handled for GET requests:</p>
  352. <pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/pushrules/
  353. </code></pre>
  354. <p>Pagination requests can also be handled, but all requests for a given
  355. room must be routed to the same instance. Additionally, care must be taken to
  356. ensure that the purge history admin API is not used while pagination requests
  357. for the room are in flight:</p>
  358. <pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/messages$
  359. </code></pre>
  360. <p>Additionally, the following endpoints should be included if Synapse is configured
  361. to use SSO (you only need to include the ones for whichever SSO provider you're
  362. using):</p>
  363. <pre><code># for all SSO providers
  364. ^/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect
  365. ^/_synapse/client/pick_idp$
  366. ^/_synapse/client/pick_username
  367. ^/_synapse/client/new_user_consent$
  368. ^/_synapse/client/sso_register$
  369. # OpenID Connect requests.
  370. ^/_synapse/client/oidc/callback$
  371. # SAML requests.
  372. ^/_synapse/client/saml2/authn_response$
  373. # CAS requests.
  374. ^/_matrix/client/(api/v1|r0|v3|unstable)/login/cas/ticket$
  375. </code></pre>
  376. <p>Ensure that all SSO logins go to a single process.
  377. For multiple workers not handling the SSO endpoints properly, see
  378. <a href="https://github.com/matrix-org/synapse/issues/7530">#7530</a> and
  379. <a href="https://github.com/matrix-org/synapse/issues/9427">#9427</a>.</p>
  380. <p>Note that a HTTP listener with <code>client</code> and <code>federation</code> resources must be
  381. configured in the <code>worker_listeners</code> option in the worker config.</p>
  382. <h4 id="load-balancing"><a class="header" href="#load-balancing">Load balancing</a></h4>
  383. <p>It is possible to run multiple instances of this worker app, with incoming requests
  384. being load-balanced between them by the reverse-proxy. However, different endpoints
  385. have different characteristics and so admins
  386. may wish to run multiple groups of workers handling different endpoints so that
  387. load balancing can be done in different ways.</p>
  388. <p>For <code>/sync</code> and <code>/initialSync</code> requests it will be more efficient if all
  389. requests from a particular user are routed to a single instance. Extracting a
  390. user ID from the access token or <code>Authorization</code> header is currently left as an
  391. exercise for the reader. Admins may additionally wish to separate out <code>/sync</code>
  392. requests that have a <code>since</code> query parameter from those that don't (and
  393. <code>/initialSync</code>), as requests that don't are known as &quot;initial sync&quot; that happens
  394. when a user logs in on a new device and can be <em>very</em> resource intensive, so
  395. isolating these requests will stop them from interfering with other users ongoing
  396. syncs.</p>
  397. <p>Federation and client requests can be balanced via simple round robin.</p>
  398. <p>The inbound federation transaction request <code>^/_matrix/federation/v1/send/</code>
  399. should be balanced by source IP so that transactions from the same remote server
  400. go to the same process.</p>
  401. <p>Registration/login requests can be handled separately purely to help ensure that
  402. unexpected load doesn't affect new logins and sign ups.</p>
  403. <p>Finally, event sending requests can be balanced by the room ID in the URI (or
  404. the full URI, or even just round robin), the room ID is the path component after
  405. <code>/rooms/</code>. If there is a large bridge connected that is sending or may send lots
  406. of events, then a dedicated set of workers can be provisioned to limit the
  407. effects of bursts of events from that bridge on events sent by normal users.</p>
  408. <h4 id="stream-writers"><a class="header" href="#stream-writers">Stream writers</a></h4>
  409. <p>Additionally, the writing of specific streams (such as events) can be moved off
  410. of the main process to a particular worker.
  411. (This is only supported with Redis-based replication.)</p>
  412. <p>To enable this, the worker must have a HTTP replication listener configured,
  413. have a <code>worker_name</code> and be listed in the <code>instance_map</code> config. The same worker
  414. can handle multiple streams, but unless otherwise documented, each stream can only
  415. have a single writer.</p>
  416. <p>For example, to move event persistence off to a dedicated worker, the shared
  417. configuration would include:</p>
  418. <pre><code class="language-yaml">instance_map:
  419. event_persister1:
  420. host: localhost
  421. port: 8034
  422. stream_writers:
  423. events: event_persister1
  424. </code></pre>
  425. <p>An example for a stream writer instance:</p>
  426. <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
  427. worker_name: event_persister1
  428. # The replication listener on the main synapse process.
  429. worker_replication_host: 127.0.0.1
  430. worker_replication_http_port: 9093
  431. worker_listeners:
  432. - type: http
  433. port: 8034
  434. resources:
  435. - names: [replication]
  436. # Enable listener if this stream writer handles endpoints for the `typing` or
  437. # `to_device` streams. Uses a different port to the `replication` listener to
  438. # avoid exposing the `replication` listener publicly.
  439. #
  440. #- type: http
  441. # port: 8035
  442. # resources:
  443. # - names: [client]
  444. worker_log_config: /etc/matrix-synapse/event-persister-log.yaml
  445. </code></pre>
  446. <p>Some of the streams have associated endpoints which, for maximum efficiency, should
  447. be routed to the workers handling that stream. See below for the currently supported
  448. streams and the endpoints associated with them:</p>
  449. <h5 id="the-events-stream"><a class="header" href="#the-events-stream">The <code>events</code> stream</a></h5>
  450. <p>The <code>events</code> stream experimentally supports having multiple writers, where work
  451. is sharded between them by room ID. Note that you <em>must</em> restart all worker
  452. instances when adding or removing event persisters. An example <code>stream_writers</code>
  453. configuration with multiple writers:</p>
  454. <pre><code class="language-yaml">stream_writers:
  455. events:
  456. - event_persister1
  457. - event_persister2
  458. </code></pre>
  459. <h5 id="the-typing-stream"><a class="header" href="#the-typing-stream">The <code>typing</code> stream</a></h5>
  460. <p>The following endpoints should be routed directly to the worker configured as
  461. the stream writer for the <code>typing</code> stream:</p>
  462. <pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/typing
  463. </code></pre>
  464. <h5 id="the-to_device-stream"><a class="header" href="#the-to_device-stream">The <code>to_device</code> stream</a></h5>
  465. <p>The following endpoints should be routed directly to the worker configured as
  466. the stream writer for the <code>to_device</code> stream:</p>
  467. <pre><code>^/_matrix/client/(r0|v3|unstable)/sendToDevice/
  468. </code></pre>
  469. <h5 id="the-account_data-stream"><a class="header" href="#the-account_data-stream">The <code>account_data</code> stream</a></h5>
  470. <p>The following endpoints should be routed directly to the worker configured as
  471. the stream writer for the <code>account_data</code> stream:</p>
  472. <pre><code>^/_matrix/client/(r0|v3|unstable)/.*/tags
  473. ^/_matrix/client/(r0|v3|unstable)/.*/account_data
  474. </code></pre>
  475. <h5 id="the-receipts-stream"><a class="header" href="#the-receipts-stream">The <code>receipts</code> stream</a></h5>
  476. <p>The following endpoints should be routed directly to the worker configured as
  477. the stream writer for the <code>receipts</code> stream:</p>
  478. <pre><code>^/_matrix/client/(r0|v3|unstable)/rooms/.*/receipt
  479. ^/_matrix/client/(r0|v3|unstable)/rooms/.*/read_markers
  480. </code></pre>
  481. <h5 id="the-presence-stream"><a class="header" href="#the-presence-stream">The <code>presence</code> stream</a></h5>
  482. <p>The following endpoints should be routed directly to the worker configured as
  483. the stream writer for the <code>presence</code> stream:</p>
  484. <pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/presence/
  485. </code></pre>
  486. <h4 id="background-tasks"><a class="header" href="#background-tasks">Background tasks</a></h4>
  487. <p>There is also support for moving background tasks to a separate
  488. worker. Background tasks are run periodically or started via replication. Exactly
  489. which tasks are configured to run depends on your Synapse configuration (e.g. if
  490. stats is enabled).</p>
  491. <p>To enable this, the worker must have a <code>worker_name</code> and can be configured to run
  492. background tasks. For example, to move background tasks to a dedicated worker,
  493. the shared configuration would include:</p>
  494. <pre><code class="language-yaml">run_background_tasks_on: background_worker
  495. </code></pre>
  496. <p>You might also wish to investigate the <code>update_user_directory_from_worker</code> and
  497. <code>media_instance_running_background_jobs</code> settings.</p>
  498. <p>An example for a dedicated background worker instance:</p>
  499. <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
  500. worker_name: background_worker
  501. # The replication listener on the main synapse process.
  502. worker_replication_host: 127.0.0.1
  503. worker_replication_http_port: 9093
  504. worker_log_config: /etc/matrix-synapse/background-worker-log.yaml
  505. </code></pre>
  506. <h4 id="updating-the-user-directory"><a class="header" href="#updating-the-user-directory">Updating the User Directory</a></h4>
  507. <p>You can designate one generic worker to update the user directory.</p>
  508. <p>Specify its name in the shared configuration as follows:</p>
  509. <pre><code class="language-yaml">update_user_directory_from_worker: worker_name
  510. </code></pre>
  511. <p>This work cannot be load-balanced; please ensure the main process is restarted
  512. after setting this option in the shared configuration!</p>
  513. <p>User directory updates allow REST endpoints matching the following regular
  514. expressions to work:</p>
  515. <pre><code>^/_matrix/client/(r0|v3|unstable)/user_directory/search$
  516. </code></pre>
  517. <p>The above endpoints can be routed to any worker, though you may choose to route
  518. it to the chosen user directory worker.</p>
  519. <p>This style of configuration supersedes the legacy <code>synapse.app.user_dir</code>
  520. worker application type.</p>
  521. <h4 id="notifying-application-services"><a class="header" href="#notifying-application-services">Notifying Application Services</a></h4>
  522. <p>You can designate one generic worker to send output traffic to Application Services.</p>
  523. <p>Specify its name in the shared configuration as follows:</p>
  524. <pre><code class="language-yaml">notify_appservices_from_worker: worker_name
  525. </code></pre>
  526. <p>This work cannot be load-balanced; please ensure the main process is restarted
  527. after setting this option in the shared configuration!</p>
  528. <p>This style of configuration supersedes the legacy <code>synapse.app.appservice</code>
  529. worker application type.</p>
  530. <h3 id="synapseapppusher"><a class="header" href="#synapseapppusher"><code>synapse.app.pusher</code></a></h3>
  531. <p>Handles sending push notifications to sygnal and email. Doesn't handle any
  532. REST endpoints itself, but you should set <code>start_pushers: False</code> in the
  533. shared configuration file to stop the main synapse sending push notifications.</p>
  534. <p>To run multiple instances at once the <code>pusher_instances</code> option should list all
  535. pusher instances by their worker name, e.g.:</p>
  536. <pre><code class="language-yaml">pusher_instances:
  537. - pusher_worker1
  538. - pusher_worker2
  539. </code></pre>
  540. <h3 id="synapseappappservice"><a class="header" href="#synapseappappservice"><code>synapse.app.appservice</code></a></h3>
  541. <p><strong>Deprecated as of Synapse v1.59.</strong> <a href="#notifying-application-services">Use <code>synapse.app.generic_worker</code> with the
  542. <code>notify_appservices_from_worker</code> option instead.</a></p>
  543. <p>Handles sending output traffic to Application Services. Doesn't handle any
  544. REST endpoints itself, but you should set <code>notify_appservices: False</code> in the
  545. shared configuration file to stop the main synapse sending appservice notifications.</p>
  546. <p>Note this worker cannot be load-balanced: only one instance should be active.</p>
  547. <h3 id="synapseappfederation_sender"><a class="header" href="#synapseappfederation_sender"><code>synapse.app.federation_sender</code></a></h3>
  548. <p>Handles sending federation traffic to other servers. Doesn't handle any
  549. REST endpoints itself, but you should set <code>send_federation: False</code> in the
  550. shared configuration file to stop the main synapse sending this traffic.</p>
  551. <p>If running multiple federation senders then you must list each
  552. instance in the <code>federation_sender_instances</code> option by their <code>worker_name</code>.
  553. All instances must be stopped and started when adding or removing instances.
  554. For example:</p>
  555. <pre><code class="language-yaml">federation_sender_instances:
  556. - federation_sender1
  557. - federation_sender2
  558. </code></pre>
  559. <h3 id="synapseappmedia_repository"><a class="header" href="#synapseappmedia_repository"><code>synapse.app.media_repository</code></a></h3>
  560. <p>Handles the media repository. It can handle all endpoints starting with:</p>
  561. <pre><code>/_matrix/media/
  562. </code></pre>
  563. <p>... and the following regular expressions matching media-specific administration APIs:</p>
  564. <pre><code>^/_synapse/admin/v1/purge_media_cache$
  565. ^/_synapse/admin/v1/room/.*/media.*$
  566. ^/_synapse/admin/v1/user/.*/media.*$
  567. ^/_synapse/admin/v1/media/.*$
  568. ^/_synapse/admin/v1/quarantine_media/.*$
  569. ^/_synapse/admin/v1/users/.*/media$
  570. </code></pre>
  571. <p>You should also set <code>enable_media_repo: False</code> in the shared configuration
  572. file to stop the main synapse running background jobs related to managing the
  573. media repository. Note that doing so will prevent the main process from being
  574. able to handle the above endpoints.</p>
  575. <p>In the <code>media_repository</code> worker configuration file, configure the http listener to
  576. expose the <code>media</code> resource. For example:</p>
  577. <pre><code class="language-yaml">worker_listeners:
  578. - type: http
  579. port: 8085
  580. resources:
  581. - names:
  582. - media
  583. </code></pre>
  584. <p>Note that if running multiple media repositories they must be on the same server
  585. and you must configure a single instance to run the background tasks, e.g.:</p>
  586. <pre><code class="language-yaml">media_instance_running_background_jobs: &quot;media-repository-1&quot;
  587. </code></pre>
  588. <p>Note that if a reverse proxy is used , then <code>/_matrix/media/</code> must be routed for both inbound client and federation requests (if they are handled separately).</p>
  589. <h3 id="synapseappuser_dir"><a class="header" href="#synapseappuser_dir"><code>synapse.app.user_dir</code></a></h3>
  590. <p><strong>Deprecated as of Synapse v1.59.</strong> <a href="#updating-the-user-directory">Use <code>synapse.app.generic_worker</code> with the
  591. <code>update_user_directory_from_worker</code> option instead.</a></p>
  592. <p>Handles searches in the user directory. It can handle REST endpoints matching
  593. the following regular expressions:</p>
  594. <pre><code>^/_matrix/client/(r0|v3|unstable)/user_directory/search$
  595. </code></pre>
  596. <p>When using this worker you must also set <code>update_user_directory: false</code> in the
  597. shared configuration file to stop the main synapse running background
  598. jobs related to updating the user directory.</p>
  599. <p>Above endpoint is not <em>required</em> to be routed to this worker. By default,
  600. <code>update_user_directory</code> is set to <code>true</code>, which means the main process
  601. will handle updates. All workers configured with <code>client</code> can handle the above
  602. endpoint as long as either this worker or the main process are configured to
  603. handle it, and are online.</p>
  604. <p>If <code>update_user_directory</code> is set to <code>false</code>, and this worker is not running,
  605. the above endpoint may give outdated results.</p>
  606. <h3 id="synapseappfrontend_proxy"><a class="header" href="#synapseappfrontend_proxy"><code>synapse.app.frontend_proxy</code></a></h3>
  607. <p>Proxies some frequently-requested client endpoints to add caching and remove
  608. load from the main synapse. It can handle REST endpoints matching the following
  609. regular expressions:</p>
  610. <pre><code>^/_matrix/client/(r0|v3|unstable)/keys/upload
  611. </code></pre>
  612. <p>If <code>use_presence</code> is False in the homeserver config, it can also handle REST
  613. endpoints matching the following regular expressions:</p>
  614. <pre><code>^/_matrix/client/(api/v1|r0|v3|unstable)/presence/[^/]+/status
  615. </code></pre>
  616. <p>This &quot;stub&quot; presence handler will pass through <code>GET</code> request but make the
  617. <code>PUT</code> effectively a no-op.</p>
  618. <p>It will proxy any requests it cannot handle to the main synapse instance. It
  619. must therefore be configured with the location of the main instance, via
  620. the <code>worker_main_http_uri</code> setting in the <code>frontend_proxy</code> worker configuration
  621. file. For example:</p>
  622. <pre><code class="language-yaml">worker_main_http_uri: http://127.0.0.1:8008
  623. </code></pre>
  624. <h3 id="historical-apps"><a class="header" href="#historical-apps">Historical apps</a></h3>
  625. <p><em>Note:</em> Historically there used to be more apps, however they have been
  626. amalgamated into a single <code>synapse.app.generic_worker</code> app. The remaining apps
  627. are ones that do specific processing unrelated to requests, e.g. the <code>pusher</code>
  628. that handles sending out push notifications for new events. The intention is for
  629. all these to be folded into the <code>generic_worker</code> app and to use config to define
  630. which processes handle the various proccessing such as push notifications.</p>
  631. <h2 id="migration-from-old-config"><a class="header" href="#migration-from-old-config">Migration from old config</a></h2>
  632. <p>There are two main independent changes that have been made: introducing Redis
  633. support and merging apps into <code>synapse.app.generic_worker</code>. Both these changes
  634. are backwards compatible and so no changes to the config are required, however
  635. server admins are encouraged to plan to migrate to Redis as the old style direct
  636. TCP replication config is deprecated.</p>
  637. <p>To migrate to Redis add the <code>redis</code> config as above, and optionally remove the
  638. TCP <code>replication</code> listener from master and <code>worker_replication_port</code> from worker
  639. config.</p>
  640. <p>To migrate apps to use <code>synapse.app.generic_worker</code> simply update the
  641. <code>worker_app</code> option in the worker configs, and where worker are started (e.g.
  642. in systemd service files, but not required for synctl).</p>
  643. <h2 id="architectural-diagram"><a class="header" href="#architectural-diagram">Architectural diagram</a></h2>
  644. <p>The following shows an example setup using Redis and a reverse proxy:</p>
  645. <pre><code> Clients &amp; Federation
  646. |
  647. v
  648. +-----------+
  649. | |
  650. | Reverse |
  651. | Proxy |
  652. | |
  653. +-----------+
  654. | | |
  655. | | | HTTP requests
  656. +-------------------+ | +-----------+
  657. | +---+ |
  658. | | |
  659. v v v
  660. +--------------+ +--------------+ +--------------+ +--------------+
  661. | Main | | Generic | | Generic | | Event |
  662. | Process | | Worker 1 | | Worker 2 | | Persister |
  663. +--------------+ +--------------+ +--------------+ +--------------+
  664. ^ ^ | ^ | | ^ | | ^ ^
  665. | | | | | | | | | | |
  666. | | | | | HTTP | | | | | |
  667. | +----------+&lt;--|---|---------+&lt;--|---|---------+ | |
  668. | | +-------------|--&gt;+-------------+ |
  669. | | | |
  670. | | | |
  671. v v v v
  672. ======================================================================
  673. Redis pub/sub channel
  674. </code></pre>
  675. </main>
  676. <nav class="nav-wrapper" aria-label="Page navigation">
  677. <!-- Mobile navigation buttons -->
  678. <a rel="prev" href="modules/porting_legacy_module.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  679. <i class="fa fa-angle-left"></i>
  680. </a>
  681. <a rel="next" href="synctl_workers.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  682. <i class="fa fa-angle-right"></i>
  683. </a>
  684. <div style="clear: both"></div>
  685. </nav>
  686. </div>
  687. </div>
  688. <nav class="nav-wide-wrapper" aria-label="Page navigation">
  689. <a rel="prev" href="modules/porting_legacy_module.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  690. <i class="fa fa-angle-left"></i>
  691. </a>
  692. <a rel="next" href="synctl_workers.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  693. <i class="fa fa-angle-right"></i>
  694. </a>
  695. </nav>
  696. </div>
  697. <script type="text/javascript">
  698. window.playground_copyable = true;
  699. </script>
  700. <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
  701. <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
  702. <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
  703. <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
  704. <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
  705. <script src="book.js" type="text/javascript" charset="utf-8"></script>
  706. <!-- Custom JS scripts -->
  707. <script type="text/javascript" src="docs/website_files/table-of-contents.js"></script>
  708. <script type="text/javascript" src="docs/website_files/version-picker.js"></script>
  709. <script type="text/javascript" src="docs/website_files/version.js"></script>
  710. </body>
  711. </html>