diff options
Diffstat (limited to 'v1.45/print.html')
| -rw-r--r-- | v1.45/print.html | 232 |
1 files changed, 91 insertions, 141 deletions
diff --git a/v1.45/print.html b/v1.45/print.html index 0970b4bafd..5bdee48138 100644 --- a/v1.45/print.html +++ b/v1.45/print.html @@ -4,55 +4,32 @@ <!-- Book generated using mdBook --> <meta charset="UTF-8"> <title>Synapse</title> - <meta name="robots" content="noindex" /> - - - - <!-- 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"> - - - + <link rel="stylesheet" href="docs/website_files/version-picker.css"> </head> <body> <!-- Provide site root to javascript --> @@ -109,7 +86,6 @@ <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"> @@ -126,32 +102,35 @@ <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 class="version-picker"> + <div class="dropdown"> + <div class="select"> + <span></span> + <i class="fa fa-chevron-down"></i> + </div> + <input type="hidden" name="version"> + <ul class="dropdown-menu"> + <!-- Versions will be added dynamically in version-picker.js --> + </ul> + </div> + </div> </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> - - - </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"> @@ -162,8 +141,6 @@ </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'); @@ -180,7 +157,7 @@ <nav class="pagetoc"></nav> </div> - <div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1> + <div style="break-before: page; page-break-before: always;"></div><h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1> <p>Welcome to the documentation repository for Synapse, a <a href="https://matrix.org">Matrix</a> homeserver implementation developed by the matrix.org core team.</p> @@ -265,7 +242,7 @@ reach out to us over email at: support (at) matrix.org</p> <p>If you've found a security issue in Synapse or any other Matrix.org Foundation project, please report it to us in accordance with our <a href="https://www.matrix.org/security-disclosure-policy/">Security Disclosure Policy</a>. Thank you!</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="installation-instructions"><a class="header" href="#installation-instructions">Installation Instructions</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="installation-instructions"><a class="header" href="#installation-instructions">Installation Instructions</a></h1> <h2 id="choosing-your-server-name"><a class="header" href="#choosing-your-server-name">Choosing your server name</a></h2> <p>It is important to choose the name for your server before you install Synapse, because it cannot be changed later.</p> @@ -662,7 +639,7 @@ failing, e.g.:</p> </code></pre> <p>If you have any other problems, feel free to ask in <a href="https://matrix.to/#/#synapse:matrix.org">#synapse:matrix.org</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="using-postgres"><a class="header" href="#using-postgres">Using Postgres</a></h1> <p>Synapse supports PostgreSQL versions 9.6 or later.</p> <h2 id="install-postgres-client-libraries"><a class="header" href="#install-postgres-client-libraries">Install postgres client libraries</a></h2> <p>Synapse will require the python postgres client library in order to @@ -859,7 +836,7 @@ downgraded and then upgraded again.</p> <p>To fix the issue shut down Synapse (including any and all workers) and run the SQL command included in the error message. Once done Synapse should start successfully.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="using-a-reverse-proxy-with-synapse"><a class="header" href="#using-a-reverse-proxy-with-synapse">Using a reverse proxy with Synapse</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="using-a-reverse-proxy-with-synapse"><a class="header" href="#using-a-reverse-proxy-with-synapse">Using a reverse proxy with Synapse</a></h1> <p>It is recommended to put a reverse proxy such as <a href="https://nginx.org/en/docs/http/ngx_http_proxy_module.html">nginx</a>, <a href="https://httpd.apache.org/docs/current/mod/mod_proxy_http.html">Apache</a>, @@ -1085,7 +1062,7 @@ Each configured HTTP listener has a <code>/health</code> endpoint which always r <code>/_synapse/admin</code>. These require authentication through an access token of an admin user. However as access to these endpoints grants the caller a lot of power, we do not recommend exposing them to the public internet without good reason.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="using-a-forward-proxy-with-synapse"><a class="header" href="#using-a-forward-proxy-with-synapse">Using a forward proxy with Synapse</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="using-a-forward-proxy-with-synapse"><a class="header" href="#using-a-forward-proxy-with-synapse">Using a forward proxy with Synapse</a></h1> <p>You can use Synapse with a forward or outbound proxy. An example of when this is necessary is in corporate environments behind a DMZ (demilitarized zone). Synapse supports routing outbound HTTP(S) requests via a proxy. Only HTTP(S) @@ -1160,7 +1137,7 @@ in Synapse can be deactivated.</p> <a href="setup/../usage/configuration/homeserver_sample_config.html">homserver.yaml</a>.</p> <pre><code class="language-yaml">use_insecure_ssl_client_just_for_testing_do_not_use: true </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="overview-1"><a class="header" href="#overview-1">Overview</a></h1> <p>This document explains how to enable VoIP relaying on your Home Server with TURN.</p> <p>The synapse Matrix Home Server supports integration with TURN server via the @@ -1426,7 +1403,7 @@ Matrix clients!</p> entry in the results.</p> </li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="delegation"><a class="header" href="#delegation">Delegation</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="delegation"><a class="header" href="#delegation">Delegation</a></h1> <p>By default, other homeservers will expect to be able to reach yours via your <code>server_name</code>, on port 8448. For example, if you set your <code>server_name</code> to <code>example.com</code> (so that your user names look like <code>@user:example.com</code>), @@ -1492,7 +1469,7 @@ is running a modern version of Synapse.</p> <h3 id="do-i-need-the-same-certificate-for-the-client-and-federation-port"><a class="header" href="#do-i-need-the-same-certificate-for-the-client-and-federation-port">Do I need the same certificate for the client and federation port?</a></h3> <p>No. There is nothing stopping you from using different certificates, particularly if you are using a reverse proxy.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="upgrading-synapse"><a class="header" href="#upgrading-synapse">Upgrading Synapse</a></h1> <p>Before upgrading check if any special steps are required to upgrade from the version you currently have installed to the current version of Synapse. The extra instructions that may be required are listed later in @@ -2698,7 +2675,7 @@ longer to restart than usual as it reinitializes the database.</p> using room aliases or by being reinvited. Alternatively, if any other homeserver sends a message to a room that the homeserver was previously in the local HS will automatically rejoin the room.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="msc1711-certificates-faq"><a class="header" href="#msc1711-certificates-faq">MSC1711 Certificates FAQ</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="msc1711-certificates-faq"><a class="header" href="#msc1711-certificates-faq">MSC1711 Certificates FAQ</a></h1> <h2 id="historical-note"><a class="header" href="#historical-note">Historical Note</a></h2> <p>This document was originally written to guide server admins through the upgrade path towards Synapse 1.0. Specifically, @@ -2974,7 +2951,7 @@ same certificate on any ports where TLS is configured.</p> <p>Synapse will reload the keys and certificates when it receives a SIGHUP - for example <code>kill -HUP $(cat homeserver.pid)</code>. Alternatively, simply restart Synapse, though this will result in downtime while it restarts.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="setting-up-federation"><a class="header" href="#setting-up-federation">Setting up federation</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="setting-up-federation"><a class="header" href="#setting-up-federation">Setting up federation</a></h1> <p>Federation is the process by which users on different servers can participate in the same room. For this to work, those other servers must be able to contact yours to send messages.</p> @@ -3026,10 +3003,10 @@ release of Synapse.</p> <p>If you want to get up and running quickly with a trio of homeservers in a private federation, there is a script in the <code>demo</code> directory. This is mainly useful just for development purposes. See <a href="https://github.com/matrix-org/synapse/tree/develop/demo/">demo/README</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="configuration-1"><a class="header" href="#configuration-1">Configuration</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="configuration-1"><a class="header" href="#configuration-1">Configuration</a></h1> <p>This section contains information on tweaking Synapse via the various options in the configuration file. A configuration file should have been generated when you <a href="usage/configuration/../../setup/installation.html">installed Synapse</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="homeserver-sample-configuration-file"><a class="header" href="#homeserver-sample-configuration-file">Homeserver Sample Configuration File</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="homeserver-sample-configuration-file"><a class="header" href="#homeserver-sample-configuration-file">Homeserver Sample Configuration File</a></h1> <p>Below is a sample homeserver configuration file. The homeserver configuration file can be tweaked to change the behaviour of your homeserver. A restart of the server is generally required to apply any changes made to this file.</p> @@ -5688,7 +5665,7 @@ redis: # #password: <secret_password> </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="logging-sample-configuration-file"><a class="header" href="#logging-sample-configuration-file">Logging Sample Configuration File</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="logging-sample-configuration-file"><a class="header" href="#logging-sample-configuration-file">Logging Sample Configuration File</a></h1> <p>Below is a sample logging configuration file. This file can be tweaked to control how your homeserver will output logs. A restart of the server is generally required to apply any changes made to this file.</p> @@ -5781,7 +5758,7 @@ root: disable_existing_loggers: false </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="structured-logging"><a class="header" href="#structured-logging">Structured Logging</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="structured-logging"><a class="header" href="#structured-logging">Structured Logging</a></h1> <p>A structured logging system can be useful when your logs are destined for a machine to parse and process. By maintaining its machine-readable characteristics, it enables more efficient searching and aggregations when consumed by software @@ -5921,7 +5898,7 @@ loggers: flexible. It allows for configuration that were not previously possible, such as sending plain logs over the network, or using different handlers for different modules.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="templates"><a class="header" href="#templates">Templates</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="templates"><a class="header" href="#templates">Templates</a></h1> <p>Synapse uses parametrised templates to generate the content of emails it sends and webpages it shows to users.</p> <p>By default, Synapse will use the templates listed <a href="https://github.com/matrix-org/synapse/tree/master/synapse/res/templates">here</a>. @@ -6191,7 +6168,7 @@ When rendering, this template is given two variables: </ul> </li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="user-authentication"><a class="header" href="#user-authentication">User Authentication</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="user-authentication"><a class="header" href="#user-authentication">User Authentication</a></h1> <p>Synapse supports multiple methods of authenticating users, either out-of-the-box or through custom pluggable authentication modules.</p> <p>Included in Synapse is support for authenticating users via:</p> @@ -6204,7 +6181,7 @@ authentication modules.</p> </ul> <p>Synapse can additionally be extended to support custom authentication schemes through optional "password auth provider" modules.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="configuring-synapse-to-authenticate-against-an-openid-connect-provider"><a class="header" href="#configuring-synapse-to-authenticate-against-an-openid-connect-provider">Configuring Synapse to authenticate against an OpenID Connect provider</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="configuring-synapse-to-authenticate-against-an-openid-connect-provider"><a class="header" href="#configuring-synapse-to-authenticate-against-an-openid-connect-provider">Configuring Synapse to authenticate against an OpenID Connect provider</a></h1> <p>Synapse can be configured to use an OpenID Connect Provider (OP) for authentication, instead of its own local password database.</p> <p>Any OP should work with Synapse, as long as it supports the authorization code @@ -6654,7 +6631,7 @@ needed to add OAuth2 capabilities to your Django projects. It supports display_name_template: "{{ user.first_name }} {{ user.last_name }}" email_template: "{{ user.email }}" </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="sso-mapping-providers"><a class="header" href="#sso-mapping-providers">SSO Mapping Providers</a></h1> <p>A mapping provider is a Python class (loaded via a Python module) that works out how to map attributes of a SSO response to Matrix-specific user attributes. Details such as user ID localpart, displayname, and even avatar @@ -6903,7 +6880,7 @@ complete registration using methods from the <code>ModuleApi</code>.</p> <p>Synapse has a built-in SAML mapping provider if a custom provider isn't specified in the config. It is located at <a href="https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py"><code>synapse.handlers.saml.DefaultSamlMappingProvider</code></a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="password-auth-provider-modules"><a class="header" href="#password-auth-provider-modules">Password auth provider modules</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="password-auth-provider-modules"><a class="header" href="#password-auth-provider-modules">Password auth provider modules</a></h1> <p>Password auth providers offer a way for server administrators to integrate their Synapse installation with an existing authentication system.</p> @@ -7012,7 +6989,7 @@ device ID), and the (now deactivated) access token.</p> wait for the <code>Awaitable</code> to complete, but the result is ignored.</p> </li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="jwt-login-type"><a class="header" href="#jwt-login-type">JWT Login Type</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="jwt-login-type"><a class="header" href="#jwt-login-type">JWT Login Type</a></h1> <p>Synapse comes with a non-standard login type to support <a href="https://en.wikipedia.org/wiki/JSON_Web_Token">JSON Web Tokens</a>. In general the documentation for @@ -7101,7 +7078,7 @@ eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.Ag71GT8v01UO3w80 </li> </ol> <p>You should now be able to use the returned access token to query the client API.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="overview-2"><a class="header" href="#overview-2">Overview</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="overview-2"><a class="header" href="#overview-2">Overview</a></h1> <p>A captcha can be enabled on your homeserver to help prevent bots from registering accounts. Synapse currently uses Google's reCAPTCHA service which requires API keys from Google.</p> @@ -7136,7 +7113,7 @@ CAPTCHA is sent. If the client is connecting through a proxy or load balancer, it may be required to use the <code>X-Forwarded-For</code> (XFF) header instead of the origin IP address. This can be configured using the <code>x_forwarded</code> directive in the listeners section of the <code>homeserver.yaml</code> configuration file.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="registering-an-application-service"><a class="header" href="#registering-an-application-service">Registering an Application Service</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="registering-an-application-service"><a class="header" href="#registering-an-application-service">Registering an Application Service</a></h1> <p>The registration of new application services depends on the homeserver used. In synapse, you need to create a new configuration file for your AS and add it to the list specified under the <code>app_service_config_files</code> config @@ -7162,7 +7139,7 @@ namespaces: <p><code>exclusive</code>: If enabled, only this application service is allowed to register users in its namespace(s). <code>group_id</code>: All users of this application service are dynamically joined to this group. This is useful for e.g user organisation or flairs.</p> <p>See the <a href="https://matrix.org/docs/spec/application_service/unstable.html">spec</a> for further details on how application services work.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="server-notices"><a class="header" href="#server-notices">Server Notices</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="server-notices"><a class="header" href="#server-notices">Server Notices</a></h1> <p>'Server Notices' are a new feature introduced in Synapse 0.30. They provide a channel whereby server administrators can send messages to users on the server.</p> <p>They are used as part of communication of the server polices (see @@ -7206,7 +7183,7 @@ displayname and avatar of the Server Notices user.</p> <h2 id="sending-notices"><a class="header" href="#sending-notices">Sending notices</a></h2> <p>To send server notices to users you can use the <a href="admin_api/server_notices.html">admin_api</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions"><a class="header" href="#support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions">Support in Synapse for tracking agreement to server terms and conditions</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions"><a class="header" href="#support-in-synapse-for-tracking-agreement-to-server-terms-and-conditions">Support in Synapse for tracking agreement to server terms and conditions</a></h1> <p>Synapse 0.30 introduces support for tracking whether users have agreed to the terms and conditions set by the administrator of a server - and blocking access to the server until they have.</p> @@ -7367,7 +7344,7 @@ consent uri for that user.</p> <p>ensure that <code>public_baseurl</code> is set in <code>homeserver.yaml</code>, and gives the base URI that clients use to connect to the server. (It is used to construct <code>consent_uri</code> in the error.)</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="url-previews-1"><a class="header" href="#url-previews-1">URL Previews</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="url-previews-1"><a class="header" href="#url-previews-1">URL Previews</a></h1> <p>The <code>GET /_matrix/media/r0/preview_url</code> endpoint provides a generic preview API for URLs which outputs <a href="https://ogp.me/">Open Graph</a> responses (with some Matrix specific additions).</p> @@ -7443,7 +7420,7 @@ provider and saves the local media metadata.</li> <p>The in-memory cache expires after 1 hour.</p> <p>Expired entries in the database cache (and their associated media files) are deleted every 10 seconds. The default expiration time is 1 hour from download.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="user-directory-api-implementation"><a class="header" href="#user-directory-api-implementation">User Directory API Implementation</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="user-directory-api-implementation"><a class="header" href="#user-directory-api-implementation">User Directory API Implementation</a></h1> <p>The user directory is currently maintained based on the 'visible' users on this particular server - i.e. ones which your account shares a room with, or who are present in a publicly viewable room present on the server.</p> @@ -7498,7 +7475,7 @@ is a local user and <code>M</code> is a local or remote user. <code>L</code> and different, but this isn't enforced by a constraint.</p> </li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="message-retention-policies"><a class="header" href="#message-retention-policies">Message retention policies</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="message-retention-policies"><a class="header" href="#message-retention-policies">Message retention policies</a></h1> <p>Synapse admins can enable support for message retention policies on their homeserver. Message retention policies exist at a room level, follow the semantics described in @@ -7654,7 +7631,7 @@ space, it will start writing new data into where the purged data was.</p> operating system, the server admin needs to run <code>VACUUM FULL;</code> (or <code>VACUUM;</code> for SQLite databases) on Synapse's database (see the related <a href="https://www.postgresql.org/docs/current/sql-vacuum.html">PostgreSQL documentation</a>).</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="modules"><a class="header" href="#modules">Modules</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="modules"><a class="header" href="#modules">Modules</a></h1> <p>Synapse supports extending its functionality by configuring external modules.</p> <h2 id="using-modules"><a class="header" href="#using-modules">Using modules</a></h2> <p>To use a module on Synapse, add it to the <code>modules</code> section of the configuration file:</p> @@ -7680,7 +7657,7 @@ configuring modules in another part of Synapse's configuration file.</p> <li>third-party rules</li> <li>presence router</li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="writing-a-module"><a class="header" href="#writing-a-module">Writing a module</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="writing-a-module"><a class="header" href="#writing-a-module">Writing a module</a></h1> <p>A module is a Python class that uses Synapse's module API to interact with the homeserver. It can register callbacks that Synapse will call on specific operations, as well as web resources to attach to Synapse's web server.</p> @@ -7730,7 +7707,7 @@ the callback name as the argument name and the function as its value. This is de in the example below. A <code>register_[...]_callbacks</code> method exists for each category.</p> <p>Callbacks for each category can be found on their respective page of the <a href="https://matrix-org.github.io/synapse">Synapse documentation website</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="spam-checker-callbacks"><a class="header" href="#spam-checker-callbacks">Spam checker callbacks</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="spam-checker-callbacks"><a class="header" href="#spam-checker-callbacks">Spam checker callbacks</a></h1> <p>Spam checker callbacks allow module developers to implement spam mitigation actions for Synapse instances. Spam checker callbacks can be registered using the module API's <code>register_spam_checker_callbacks</code> method.</p> @@ -7908,7 +7885,7 @@ class ListSpamChecker: async def check_event_for_spam(self, event: "synapse.events.EventBase") -> Union[bool, str]: return event.sender not in self.evil_users </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="third-party-rules-callbacks"><a class="header" href="#third-party-rules-callbacks">Third party rules callbacks</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="third-party-rules-callbacks"><a class="header" href="#third-party-rules-callbacks">Third party rules callbacks</a></h1> <p>Third party rules callbacks allow module developers to add extra checks to verify the validity of incoming events. Third party event rules callbacks can be registered using the module API's <code>register_third_party_rules_callbacks</code> method.</p> @@ -8005,7 +7982,7 @@ class EventCensorer: event_dict["content"] = new_event_content return event_dict </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="presence-router-callbacks"><a class="header" href="#presence-router-callbacks">Presence router callbacks</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="presence-router-callbacks"><a class="header" href="#presence-router-callbacks">Presence router callbacks</a></h1> <p>Presence router callbacks allow module developers to specify additional users (local or remote) to receive certain presence updates from local users. Presence router callbacks can be registered using the module API's <code>register_presence_router_callbacks</code> method.</p> @@ -8077,7 +8054,7 @@ class CustomPresenceRouter: return set() </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-callbacks"><a class="header" href="#account-validity-callbacks">Account validity callbacks</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-callbacks"><a class="header" href="#account-validity-callbacks">Account validity callbacks</a></h1> <p>Account validity callbacks allow module developers to add extra steps to verify the validity on an account, i.e. see if a user can be granted access to their account on the Synapse instance. Account validity callbacks can be registered using the module API's @@ -8099,7 +8076,7 @@ invalidate the user's access token.</p> <p>Called after successfully registering a user, in case the module needs to perform extra operations to keep track of them. (e.g. add them to a database table). The user is represented by their Matrix user ID.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="porting-an-existing-module-that-uses-the-old-interface"><a class="header" href="#porting-an-existing-module-that-uses-the-old-interface">Porting an existing module that uses the old interface</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="porting-an-existing-module-that-uses-the-old-interface"><a class="header" href="#porting-an-existing-module-that-uses-the-old-interface">Porting an existing module that uses the old interface</a></h1> <p>In order to port a module that uses Synapse's old module interface, its author needs to:</p> <ul> <li>ensure the module's callbacks are all asynchronous.</li> @@ -8114,7 +8091,7 @@ more info).</p> <p>The module's author should also update any example in the module's configuration to only use the new <code>modules</code> section in Synapse's configuration file (see <a href="modules/index.html#using-modules">this section</a> for more info).</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="scaling-synapse-via-workers"><a class="header" href="#scaling-synapse-via-workers">Scaling synapse via workers</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="scaling-synapse-via-workers"><a class="header" href="#scaling-synapse-via-workers">Scaling synapse via workers</a></h1> <p>For small instances it recommended to run Synapse in the default monolith mode. For larger instances where performance is a concern it can be helpful to split out functionality into multiple separate python processes. These processes are @@ -8552,7 +8529,7 @@ in systemd service files, but not required for synctl).</p> ==================================================================== Redis pub/sub channel </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h3 id="using-synctl-with-workers"><a class="header" href="#using-synctl-with-workers">Using synctl with workers</a></h3> +<div style="break-before: page; page-break-before: always;"></div><h3 id="using-synctl-with-workers"><a class="header" href="#using-synctl-with-workers">Using synctl with workers</a></h3> <p>If you want to use <code>synctl</code> to manage your synapse processes, you will need to create an an additional configuration file for the main synapse process. That configuration should look like this:</p> @@ -8575,7 +8552,7 @@ notifications.</p> <p>To manipulate a specific worker, you pass the -w option to synctl:</p> <pre><code>synctl -w $CONFIG/workers/worker1.yaml restart </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></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> +<div style="break-before: page; page-break-before: always;"></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 @@ -8667,14 +8644,14 @@ 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> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="administration"><a class="header" href="#administration">Administration</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="administration"><a class="header" href="#administration">Administration</a></h1> <p>This section contains information on managing your Synapse homeserver. This includes:</p> <ul> <li>Managing users, rooms and media via the Admin API.</li> <li>Setting up metrics and monitoring to give you insight into your homeserver's health.</li> <li>Configuring structured logging.</li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="the-admin-api"><a class="header" href="#the-admin-api">The Admin API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="the-admin-api"><a class="header" href="#the-admin-api">The Admin API</a></h1> <h2 id="authenticate-as-a-server-admin"><a class="header" href="#authenticate-as-a-server-admin">Authenticate as a server admin</a></h2> <p>Many of the API calls in the admin api will require an <code>access_token</code> for a server admin. (Note that a server admin is distinct from a room admin.)</p> @@ -8692,7 +8669,7 @@ providing the token as either a query parameter or a request header. To add it a </code></pre> <p>For more details on access tokens in Matrix, please refer to the complete <a href="https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens">matrix spec documentation</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-api"><a class="header" href="#account-validity-api">Account validity API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="account-validity-api"><a class="header" href="#account-validity-api">Account validity API</a></h1> <p>This API allows a server administrator to manage the validity of an account. To use it, you must enable the account validity feature (under <code>account_validity</code>) in Synapse's configuration.</p> @@ -8719,7 +8696,7 @@ milliseconds since epoch:</p> "expiration_ts": 0 } </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="delete-a-local-group"><a class="header" href="#delete-a-local-group">Delete a local group</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="delete-a-local-group"><a class="header" href="#delete-a-local-group">Delete a local group</a></h1> <p>This API lets a server admin delete a local group. Doing so will kick all users out of the group so that their clients will correctly handle the group being deleted.</p> @@ -8728,7 +8705,7 @@ being deleted.</p> </code></pre> <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="show-reported-events"><a class="header" href="#show-reported-events">Show reported events</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="show-reported-events"><a class="header" href="#show-reported-events">Show reported events</a></h1> <p>This API returns information about reported events.</p> <p>The api is:</p> <pre><code>GET /_synapse/admin/v1/event_reports?from=0&limit=10 @@ -8883,7 +8860,7 @@ was reported.</li> have a canonical alias set.</li> <li><code>event_json</code>: object - Details of the original event that was reported.</li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="contents-1"><a class="header" href="#contents-1">Contents</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="contents-1"><a class="header" href="#contents-1">Contents</a></h1> <ul> <li><a href="admin_api/media_admin_api.html#querying-media">Querying media</a> <ul> @@ -9123,7 +9100,7 @@ All cached media that was last accessed before this timestamp will be removed.</ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin API</a>.</p> <p>If the user re-requests purged remote media, synapse will re-request the media from the originating server.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="purge-history-api"><a class="header" href="#purge-history-api">Purge History API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="purge-history-api"><a class="header" href="#purge-history-api">Purge History API</a></h1> <p>The purge history API allows server admins to purge historic events from their database, reclaiming disk space.</p> <p>Depending on the amount of history being purged a call to the API may take @@ -9173,7 +9150,7 @@ server admin.</p> <p>To reclaim the disk space and return it to the operating system, you need to run <code>VACUUM FULL;</code> on the database.</p> <p><a href="https://www.postgresql.org/docs/current/sql-vacuum.html">https://www.postgresql.org/docs/current/sql-vacuum.html</a></p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="shared-secret-registration"><a class="header" href="#shared-secret-registration">Shared-Secret Registration</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="shared-secret-registration"><a class="header" href="#shared-secret-registration">Shared-Secret Registration</a></h1> <p>This API allows for the creation of users in an administrative and non-interactive way. This is generally used for bootstrapping a Synapse instance with administrator accounts.</p> @@ -9234,7 +9211,7 @@ def generate_mac(nonce, user, password, admin=False, user_type=None): return mac.hexdigest() </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="registration-tokens"><a class="header" href="#registration-tokens">Registration Tokens</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="registration-tokens"><a class="header" href="#registration-tokens">Registration Tokens</a></h1> <p>This API allows you to manage tokens which can be used to authenticate registration requests, as proposed in <a href="https://github.com/matrix-org/matrix-doc/blob/main/proposals/3231-token-authenticated-registration.md">MSC3231</a>. @@ -9472,7 +9449,7 @@ the <a href="https://matrix.org/docs/spec/client_server/r0.6.1#api-standards">Ma "error": "No such registration token: 1234" } </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="edit-room-membership-api"><a class="header" href="#edit-room-membership-api">Edit Room Membership API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="edit-room-membership-api"><a class="header" href="#edit-room-membership-api">Edit Room Membership API</a></h1> <p>This API allows an administrator to join an user account with a given <code>user_id</code> to a room with a given <code>room_id_or_alias</code>. You can only modify the membership of local users. The server administrator must be in the room and have permission to @@ -9498,7 +9475,7 @@ server admin: see <a href="admin_api/../usage/administration/admin_api">Admin AP "room_id": "!636q39766251:server.com" } </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="contents-2"><a class="header" href="#contents-2">Contents</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="contents-2"><a class="header" href="#contents-2">Contents</a></h1> <ul> <li><a href="admin_api/rooms.html#list-room-api">List Room API</a></li> <li><a href="admin_api/rooms.html#room-details-api">Room Details API</a></li> @@ -10123,7 +10100,7 @@ that were deleted.</p> ] } </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="server-notices-1"><a class="header" href="#server-notices-1">Server Notices</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="server-notices-1"><a class="header" href="#server-notices-1">Server Notices</a></h1> <p>The API to send notices is as follows:</p> <pre><code>POST /_synapse/admin/v1/send_server_notice </code></pre> @@ -10154,7 +10131,7 @@ ignored in the same way as with <code>PUT /_matrix/client/r0/rooms/{roomId}/send </code></pre> <p>Note that server notices must be enabled in <code>homeserver.yaml</code> before this API can be used. See <a href="admin_api/../server_notices.html">the server notices documentation</a> for more information.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="users-media-usage-statistics"><a class="header" href="#users-media-usage-statistics">Users' media usage statistics</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="users-media-usage-statistics"><a class="header" href="#users-media-usage-statistics">Users' media usage statistics</a></h1> <p>Returns information about all local media usage of users. Gives the possibility to filter them by time and user.</p> <p>The API is:</p> @@ -10230,7 +10207,7 @@ about the user and their local media. Objects contain the following fields: <li><code>next_token</code> - integer - Opaque value used for pagination. See above.</li> <li><code>total</code> - integer - Total number of users after filtering.</li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="user-admin-api"><a class="header" href="#user-admin-api">User Admin API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="user-admin-api"><a class="header" href="#user-admin-api">User Admin API</a></h1> <h2 id="query-user-account"><a class="header" href="#query-user-account">Query User Account</a></h2> <p>This API returns information about a specific user account.</p> <p>The api is:</p> @@ -11147,7 +11124,7 @@ for more information.</p> <p>The request and response format is the same as the <a href="https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-register-available">/_matrix/client/r0/register/available</a> API.</p> <p>To use it, you will need to authenticate by providing an <code>access_token</code> for a server admin: <a href="admin_api/../usage/administration/admin_api">Admin API</a></p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="version-api"><a class="header" href="#version-api">Version API</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="version-api"><a class="header" href="#version-api">Version API</a></h1> <p>This API returns the running Synapse version and the Python version on which Synapse is being run. This is useful when a Synapse instance is behind a proxy that does not forward the 'Server' header (which also @@ -11161,7 +11138,7 @@ contains Synapse version information).</p> "python_version": "3.6.8" } </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="using-the-synapse-manhole"><a class="header" href="#using-the-synapse-manhole">Using the synapse manhole</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="using-the-synapse-manhole"><a class="header" href="#using-the-synapse-manhole">Using the synapse manhole</a></h1> <p>The "manhole" allows server administrators to access a Python shell on a running Synapse installation. This is a very powerful mechanism for administration and debugging.</p> @@ -11228,7 +11205,7 @@ parts of the process.</p> >>> defer.ensureDeferred(hs.get_datastore().get_event('$1416420717069yeQaw:matrix.org')) <Deferred at 0x7ff253fc6998 current result: <FrozenEvent event_id='$1416420717069yeQaw:matrix.org', type='m.room.create', state_key=''>> </code></pre> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="how-to-monitor-synapse-metrics-using-prometheus"><a class="header" href="#how-to-monitor-synapse-metrics-using-prometheus">How to monitor Synapse metrics using Prometheus</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-monitor-synapse-metrics-using-prometheus"><a class="header" href="#how-to-monitor-synapse-metrics-using-prometheus">How to monitor Synapse metrics using Prometheus</a></h1> <ol> <li> <p>Install Prometheus:</p> @@ -11468,7 +11445,7 @@ renamed.</p> <tr><td>python_twisted_reactor_pending_calls</td><td>reactor_pending_calls</td></tr> <tr><td>python_twisted_reactor_tick_time</td><td>reactor_tick_time</td></tr> </tbody></table> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="request-log-format"><a class="header" href="#request-log-format">Request log format</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="request-log-format"><a class="header" href="#request-log-format">Request log format</a></h1> <p>HTTP request logs are written by synapse (see <a href="usage/administration/../synapse/http/site.py"><code>site.py</code></a> for details).</p> <p>See the following for how to decode the dense data available from the default logging configuration.</p> <pre><code>2020-10-01 12:00:00,000 - synapse.access.http.8008 - 311 - INFO - PUT-1000- 192.168.0.1 - 8008 - {another-matrix-server.com} Processed request: 0.100sec/-0.000sec (0.000sec, 0.000sec) (0.001sec/0.090sec/3) 11B !200 "PUT /_matrix/federation/v1/send/1600000000000 HTTP/1.1" "Synapse/1.20.1" [0 dbevts] @@ -11503,7 +11480,7 @@ the same data, but only the first request will report time/transactions in <code>KKKK</code>/<code>LLLL</code>/<code>MMMM</code>/<code>NNNN</code>/<code>OOOO</code> - the others will be awaiting the first query to return a response and will simultaneously return with the first request, but with very small processing times.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1> <p>This document aims to get you started with contributing to Synapse!</p> <h1 id="1-who-can-contribute-to-synapse"><a class="header" href="#1-who-can-contribute-to-synapse">1. Who can contribute to Synapse?</a></h1> <p>Everyone is welcome to contribute code to <a href="https://github.com/matrix-org">matrix.org @@ -11647,7 +11624,7 @@ so we can run a specific test in this container with e.g.</p> <code>.tox-pg-container</code> and uses this as a tox environment. The output of any <code>trial</code> runs goes into <code>_trial_temp</code> in your synapse source directory — the same as running <code>trial</code> directly on your host machine.</p> -<h2 id="run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta"><a class="header" href="#run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgsytestsytesta">Run the integration tests (<a href="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2> +<h2 id="run-the-integration-tests-sytest"><a class="header" href="#run-the-integration-tests-sytest">Run the integration tests (<a href="https://github.com/matrix-org/sytest">Sytest</a>).</a></h2> <p>The integration tests are a more comprehensive suite of tests. They run a full version of Synapse, including your changes, to check if anything was broken. They are slower than the unit tests but will @@ -11657,7 +11634,7 @@ configuration:</p> <pre><code class="language-sh">$ docker run --rm -it -v /path/where/you/have/cloned/the/repository\:/src:ro -v /path/to/where/you/want/logs\:/logs matrixdotorg/sytest-synapse:buster </code></pre> <p>This configuration should generally cover your needs. For more details about other configurations, see <a href="https://github.com/matrix-org/sytest/blob/develop/docker/README.md">documentation in the SyTest repo</a>.</p> -<h2 id="run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgcomplementcomplementa"><a class="header" href="#run-the-integration-tests-a-hrefhttpsgithubcommatrix-orgcomplementcomplementa">Run the integration tests (<a href="https://github.com/matrix-org/complement">Complement</a>).</a></h2> +<h2 id="run-the-integration-tests-complement"><a class="header" href="#run-the-integration-tests-complement">Run the integration tests (<a href="https://github.com/matrix-org/complement">Complement</a>).</a></h2> <p><a href="https://github.com/matrix-org/complement">Complement</a> is a suite of black box tests that can be run on any homeserver implementation. It can also be thought of as end-to-end (e2e) tests.</p> <p>It's often nice to develop on Synapse and write Complement tests at the same time. Here is how to run your local Synapse checkout against your local Complement checkout.</p> @@ -11851,7 +11828,7 @@ matrix together all the fragmented communication technologies out there we are reliant on contributions and collaboration from the community to do so. So please get involved - and we hope you have as much fun hacking on Matrix as we do!</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="code-style"><a class="header" href="#code-style">Code Style</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="code-style"><a class="header" href="#code-style">Code Style</a></h1> <h2 id="formatting-tools"><a class="header" href="#formatting-tools">Formatting tools</a></h2> <p>The Synapse codebase uses a number of code formatting tools in order to quickly and automatically check for formatting (and sometimes logical) @@ -12029,7 +12006,7 @@ frobber: and is maintained by a script, <code>scripts-dev/generate_sample_config</code>. Making sure that the output from this script matches the desired format is left as an exercise for the reader!</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="some-notes-on-how-we-use-git"><a class="header" href="#some-notes-on-how-we-use-git">Some notes on how we use git</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="some-notes-on-how-we-use-git"><a class="header" href="#some-notes-on-how-we-use-git">Some notes on how we use git</a></h1> <h2 id="on-keeping-the-commit-history-clean"><a class="header" href="#on-keeping-the-commit-history-clean">On keeping the commit history clean</a></h2> <p>In an ideal world, our git commit history would be a linear progression of commits each of which contains a single change building on what came @@ -12131,7 +12108,7 @@ that our active branches are ordered thus, from more-stable to less-stable:</p> <ul> <li><code>master</code> (tracks our last release).</li> <li><code>release-vX.Y</code> (the branch where we prepare the next release)<sup - id="a3"><a href="development/git.html#f3">3</a></sup>.</li> +id="a3"><a href="development/git.html#f3">3</a></sup>.</li> <li>PR branches which are targeting the release.</li> <li><code>develop</code> (our "mainline" branch containing our bleeding-edge).</li> <li>regular PR branches.</li> @@ -12150,7 +12127,7 @@ most intuitive name. <a href="development/git.html#a1">^</a></p> <p><b id="f3">[3]</b>: Very, very occasionally (I think this has happened once in the history of Synapse), we've had two releases in flight at once. Obviously, <code>release-v1.2</code> is more-stable than <code>release-v1.3</code>. <a href="development/git.html#a3">^</a></p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="opentracing"><a class="header" href="#opentracing">OpenTracing</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="opentracing"><a class="header" href="#opentracing">OpenTracing</a></h1> <h2 id="background"><a class="header" href="#background">Background</a></h2> <p>OpenTracing is a semi-standard being adopted by a number of distributed tracing platforms. It is a common api for facilitating vendor-agnostic @@ -12223,7 +12200,7 @@ logged to OpenTracing's logs.</li> <h2 id="configuring-jaeger"><a class="header" href="#configuring-jaeger">Configuring Jaeger</a></h2> <p>Sampling strategies can be set as in this document: <a href="https://www.jaegertracing.io/docs/latest/sampling/">https://www.jaegertracing.io/docs/latest/sampling/</a>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="synapse-database-schema-files"><a class="header" href="#synapse-database-schema-files">Synapse database schema files</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="synapse-database-schema-files"><a class="header" href="#synapse-database-schema-files">Synapse database schema files</a></h1> <p>Synapse's database schema is stored in the <code>synapse.storage.schema</code> module.</p> <h2 id="logical-databases"><a class="header" href="#logical-databases">Logical databases</a></h2> <p>Synapse supports splitting its datastore across multiple physical databases (which can @@ -12344,7 +12321,7 @@ default value is the <strong>string</strong> <code>"FALSE"</code> - wh in Python, evaluates to <code>True</code>.</p> </li> </ul> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="implementing-experimental-features-in-synapse"><a class="header" href="#implementing-experimental-features-in-synapse">Implementing experimental features in Synapse</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="implementing-experimental-features-in-synapse"><a class="header" href="#implementing-experimental-features-in-synapse">Implementing experimental features in Synapse</a></h1> <p>It can be desirable to implement "experimental" features which are disabled by default and must be explicitly enabled via the Synapse configuration. This is applicable for features which:</p> @@ -12377,7 +12354,7 @@ but one should be used if unsure.</p> <p>New experimental configuration flags should be added under the <code>experimental</code> configuration key (see the <code>synapse.config.experimental</code> file) and either explain (briefly) what is being enabled, or include the MSC number.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="log-contexts"><a class="header" href="#log-contexts">Log Contexts</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="log-contexts"><a class="header" href="#log-contexts">Log Contexts</a></h1> <p>To help track the processing of individual requests, synapse uses a '<code>log context</code>' to track which request it is handling at any given moment. This is done via a thread-local variable; a <code>logging.Filter</code> is @@ -12673,7 +12650,7 @@ chain are dropped. Dropping the the reference to an awaitable you're supposed to be awaiting is bad practice, so this doesn't actually happen too much. Unfortunately, when it does happen, it will lead to leaked logcontexts which are incredibly hard to track down.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="replication-architecture"><a class="header" href="#replication-architecture">Replication Architecture</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="replication-architecture"><a class="header" href="#replication-architecture">Replication Architecture</a></h1> <h2 id="motivation"><a class="header" href="#motivation">Motivation</a></h2> <p>We'd like to be able to split some of the work that synapse does into multiple python processes. In theory multiple synapse processes could @@ -12701,7 +12678,7 @@ minimal.</p> <p>There are read-only version of the synapse storage layer in <code>synapse/replication/slave/storage</code> that use the response of the replication API to invalidate their caches.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="tcp-replication"><a class="header" href="#tcp-replication">TCP Replication</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="tcp-replication"><a class="header" href="#tcp-replication">TCP Replication</a></h1> <h2 id="motivation-1"><a class="header" href="#motivation-1">Motivation</a></h2> <p>Previously the workers used an HTTP long poll mechanism to get updates from the master, which had the problem of causing a lot of duplicate @@ -12896,7 +12873,7 @@ workers understand to mean to expand to invalidate the correct caches.</p> <li><code>cs_cache_fake</code> ─ invalidates caches that depend on the current state</li> </ol> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="internal-documentation"><a class="header" href="#internal-documentation">Internal Documentation</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="internal-documentation"><a class="header" href="#internal-documentation">Internal Documentation</a></h1> <p>This section covers implementation documentation for various parts of Synapse.</p> <p>If a developer is planning to make a change to a feature of Synapse, it can be useful for general documentation of how that feature is implemented to be available. This saves the @@ -12905,7 +12882,7 @@ code.</p> <p>Documentation that would be more useful for the perspective of a system administrator, rather than a developer who's intending to change to code, should instead be placed under the Usage section of the documentation.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-saml-as-a-developer-without-a-server"><a class="header" href="#how-to-test-saml-as-a-developer-without-a-server">How to test SAML as a developer without a server</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-saml-as-a-developer-without-a-server"><a class="header" href="#how-to-test-saml-as-a-developer-without-a-server">How to test SAML as a developer without a server</a></h1> <p>https://fujifish.github.io/samling/samling.html (https://github.com/fujifish/samling) is a great resource for being able to tinker with the SAML options within Synapse without needing to deploy and configure a complicated software stack.</p> <p>To make Synapse (and therefore Element) use it:</p> @@ -12943,7 +12920,7 @@ The response must also be signed.</li> <p>If you try and repeat this process, you may be automatically logged in using the information you gave previously. To fix this, open your developer console (<code>F12</code> or <code>Ctrl+Shift+I</code>) while on the samling page and clear the site data. In Chrome, this will be a button on the Application tab.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-cas-as-a-developer-without-a-server"><a class="header" href="#how-to-test-cas-as-a-developer-without-a-server">How to test CAS as a developer without a server</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-test-cas-as-a-developer-without-a-server"><a class="header" href="#how-to-test-cas-as-a-developer-without-a-server">How to test CAS as a developer without a server</a></h1> <p>The <a href="https://github.com/jbittel/django-mama-cas">django-mama-cas</a> project is an easy to run CAS implementation built on top of Django.</p> <h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2> @@ -13005,7 +12982,7 @@ and that the CAS server is on port 8000, both on localhost.</p> <li>http://localhost:8000/admin/</li> <li>Click "logout" in the top right.</li> </ol> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="room-dag-concepts"><a class="header" href="#room-dag-concepts">Room DAG concepts</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="room-dag-concepts"><a class="header" href="#room-dag-concepts">Room DAG concepts</a></h1> <h2 id="edges"><a class="header" href="#edges">Edges</a></h2> <p>The word "edge" comes from graph theory lingo. An edge is just a connection between two events. In Synapse, we connect events by specifying their @@ -13056,7 +13033,7 @@ mappings of <code>event_id -> state_group</code> and <code>state_group -> <h3 id="stage-group-edges"><a class="header" href="#stage-group-edges">Stage group edges</a></h3> <p>TODO: <code>state_group_edges</code> is a further optimization... notes from @Azrenbeth, https://pastebin.com/seUGVGeT</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="auth-chain-difference-algorithm"><a class="header" href="#auth-chain-difference-algorithm">Auth Chain Difference Algorithm</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="auth-chain-difference-algorithm"><a class="header" href="#auth-chain-difference-algorithm">Auth Chain Difference Algorithm</a></h1> <p>The auth chain difference algorithm is used by V2 state resolution, where a naive implementation can be a significant source of CPU and DB usage.</p> <h3 id="definitions"><a class="header" href="#definitions">Definitions</a></h3> @@ -13147,7 +13124,7 @@ level).</li> </ol> <p>So the final result is: Bob's second join <code>(2,2)</code>, the second power level <code>(3,2)</code> and both of Alice's joins <code>(4,2)</code> & <code>(4,3)</code>.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="media-repository"><a class="header" href="#media-repository">Media Repository</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="media-repository"><a class="header" href="#media-repository">Media Repository</a></h1> <p><em>Synapse implementation-specific details for the media repository</em></p> <p>The media repository is where attachments and avatar photos are stored. It stores attachment content and thumbnails for media uploaded by local users. @@ -13168,7 +13145,7 @@ remote content is assigned a local <code>"filesystem_id"</code> to ens directory structure <code>"remote_content/server_name/aa/bb/ccccccccdddddddddddd"</code> is appropriate. Thumbnails for remote content are stored under <code>"remote_thumbnail/server_name/..."</code></p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="room-and-user-statistics"><a class="header" href="#room-and-user-statistics">Room and User Statistics</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="room-and-user-statistics"><a class="header" href="#room-and-user-statistics">Room and User Statistics</a></h1> <p>Synapse maintains room and user statistics in various tables. These can be used for administrative purposes but are also used when generating the public room directory.</p> @@ -13183,7 +13160,7 @@ table. Each subject can have only one.</li> <h3 id="overview-4"><a class="header" href="#overview-4">Overview</a></h3> <p>Stats correspond to the present values. Current rows contain the most up-to-date statistics for a room. Each subject can only have one entry.</p> -<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="deprecation-policy-for-platform-dependencies"><a class="header" href="#deprecation-policy-for-platform-dependencies">Deprecation Policy for Platform Dependencies</a></h1> +<div style="break-before: page; page-break-before: always;"></div><h1 id="deprecation-policy-for-platform-dependencies"><a class="header" href="#deprecation-policy-for-platform-dependencies">Deprecation Policy for Platform Dependencies</a></h1> <p>Synapse has a number of platform dependencies, including Python and PostgreSQL. This document outlines the policy towards which versions we support, and when we drop support for versions in the future.</p> @@ -13209,61 +13186,34 @@ to constantly update their platform dependencies to the latest versions.</p> <nav class="nav-wrapper" aria-label="Page navigation"> <!-- Mobile navigation buttons --> - - - - <div style="clear: both"></div> </nav> </div> </div> <nav class="nav-wide-wrapper" aria-label="Page navigation"> - - - </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> - - - - + <script type="text/javascript" src="docs/website_files/version-picker.js"></script> + <script type="text/javascript" src="docs/website_files/version.js"></script> <script type="text/javascript"> window.addEventListener('load', function() { window.setTimeout(window.print, 100); }); </script> - - - </body> -</html> \ No newline at end of file +</html> |