mirror of
https://github.com/element-hq/synapse.git
synced 2026-10-22 11:42:26 +00:00
deploy: 78a70a2e0b
This commit is contained in:
erikjohnston committed
1 parent
e884941878
commit
e7c67ecf11
73 files changed
+1036
-731
No files matched your search
+335
-223
@@ -101,7 +101,7 @@
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<div class="sidebar-scrollbox">
|
||||
<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 "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</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/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="usage/configuration/user_authentication/index.html">User Authentication</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="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></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></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="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.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">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="admin_api/delete_group.html">Delete Group</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="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_noLine truncated
|
||||
<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 "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</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/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 "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></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></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="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.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">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="admin_api/delete_group.html">Delete Group</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="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html"Line truncated
|
||||
</div>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||||
</nav>
|
||||
@@ -1553,9 +1553,15 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
|
||||
<li><code>POST /_synapse/admin/v1/purge_room</code></li>
|
||||
<li><code>POST /_synapse/admin/v1/shutdown_room/<room_id></code></li>
|
||||
</ul>
|
||||
<p>Any scripts still using the above APIs should be converted to use the
|
||||
<p>Any scripts still using the above APIs should be converted to use the
|
||||
<a href="https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#delete-room-api">Delete Room API</a>.</p>
|
||||
<h1 id="upgrading-to-v1xx0-1"><a class="header" href="#upgrading-to-v1xx0-1">Upgrading to v1.xx.0</a></h1>
|
||||
<h2 id="user-interactive-authentication-fallback-templates-can-now-display-errors"><a class="header" href="#user-interactive-authentication-fallback-templates-can-now-display-errors">User-interactive authentication fallback templates can now display errors</a></h2>
|
||||
<p>This may affect you if you make use of custom HTML templates for the
|
||||
<a href="../synapse/res/templates/recaptcha.html">reCAPTCHA</a> or
|
||||
<a href="../synapse/res/templates/terms.html">terms</a> fallback pages.</p>
|
||||
<p>The template is now provided an <code>error</code> variable if the authentication
|
||||
process failed. See the default templates linked above for an example.</p>
|
||||
<h1 id="upgrading-to-v1410"><a class="header" href="#upgrading-to-v1410">Upgrading to v1.41.0</a></h1>
|
||||
<h2 id="add-support-for-routing-outbound-http-requests-via-a-proxy-for-federation"><a class="header" href="#add-support-for-routing-outbound-http-requests-via-a-proxy-for-federation">Add support for routing outbound HTTP requests via a proxy for federation</a></h2>
|
||||
<p>Since Synapse 1.6.0 (2019-11-26) you can set a proxy for outbound HTTP requests via
|
||||
http_proxy/https_proxy environment variables. This proxy was set for:</p>
|
||||
@@ -1579,12 +1585,19 @@ recommend to verify the configuration. It may be necessary to adjust the <code>n
|
||||
environment variable.</p>
|
||||
<p>See <a href="setup/forward_proxy.html">using a forward proxy with Synapse documentation</a> for
|
||||
details.</p>
|
||||
<h2 id="user-interactive-authentication-fallback-templates-can-now-display-errors"><a class="header" href="#user-interactive-authentication-fallback-templates-can-now-display-errors">User-interactive authentication fallback templates can now display errors</a></h2>
|
||||
<p>This may affect you if you make use of custom HTML templates for the
|
||||
<a href="../synapse/res/templates/recaptcha.html">reCAPTCHA</a> or
|
||||
<a href="../synapse/res/templates/terms.html">terms</a> fallback pages.</p>
|
||||
<p>The template is now provided an <code>error</code> variable if the authentication
|
||||
process failed. See the default templates linked above for an example.</p>
|
||||
<h2 id="deprecation-of-template_dir"><a class="header" href="#deprecation-of-template_dir">Deprecation of <code>template_dir</code></a></h2>
|
||||
<p>The <code>template_dir</code> settings in the <code>sso</code>, <code>account_validity</code> and <code>email</code> sections of the
|
||||
configuration file are now deprecated. Server admins should use the new
|
||||
<code>templates.custom_template_directory</code> setting in the configuration file and use one single
|
||||
custom template directory for all aforementioned features. Template file names remain
|
||||
unchanged. See <a href="https://matrix-org.github.io/synapse/latest/templates.html">the related documentation</a>
|
||||
for more information and examples.</p>
|
||||
<p>We plan to remove support for these settings in October 2021.</p>
|
||||
<h2 id="_synapseadminv1usersuseridmedia-must-be-handled-by-media-workers"><a class="header" href="#_synapseadminv1usersuseridmedia-must-be-handled-by-media-workers"><code>/_synapse/admin/v1/users/{userId}/media</code> must be handled by media workers</a></h2>
|
||||
<p>The <a href="https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository">media repository worker documentation</a>
|
||||
has been updated to reflect that calls to <code>/_synapse/admin/v1/users/{userId}/media</code>
|
||||
must now be handled by media repository workers. This is due to the new <code>DELETE</code> method
|
||||
of this endpoint modifying the media store.</p>
|
||||
<h1 id="upgrading-to-v1390"><a class="header" href="#upgrading-to-v1390">Upgrading to v1.39.0</a></h1>
|
||||
<h2 id="deprecation-of-the-current-third-party-rules-module-interface"><a class="header" href="#deprecation-of-the-current-third-party-rules-module-interface">Deprecation of the current third-party rules module interface</a></h2>
|
||||
<p>The current third-party rules module interface is deprecated in favour of the new generic
|
||||
@@ -3532,6 +3545,19 @@ retention:
|
||||
#
|
||||
#next_link_domain_whitelist: ["matrix.org"]
|
||||
|
||||
# Templates to use when generating email or HTML page contents.
|
||||
#
|
||||
templates:
|
||||
# Directory in which Synapse will try to find template files to use to generate
|
||||
# email or HTML page contents.
|
||||
# If not set, or a file is not found within the template directory, a default
|
||||
# template from within the Synapse package will be used.
|
||||
#
|
||||
# See https://matrix-org.github.io/synapse/latest/templates.html for more
|
||||
# information about using custom templates.
|
||||
#
|
||||
#custom_template_directory: /path/to/custom/templates/
|
||||
|
||||
|
||||
## TLS ##
|
||||
|
||||
@@ -4862,6 +4888,9 @@ cas_config:
|
||||
# Additional settings to use with single-sign on systems such as OpenID Connect,
|
||||
# SAML2 and CAS.
|
||||
#
|
||||
# Server admins can configure custom templates for pages related to SSO. See
|
||||
# https://matrix-org.github.io/synapse/latest/templates.html for more information.
|
||||
#
|
||||
sso:
|
||||
# A list of client URLs which are whitelisted so that the user does not
|
||||
# have to confirm giving access to their account to the URL. Any client
|
||||
@@ -4894,169 +4923,6 @@ sso:
|
||||
#
|
||||
#update_profile_information: true
|
||||
|
||||
# Directory in which Synapse will try to find the template files below.
|
||||
# If not set, or the files named below are not found within the template
|
||||
# directory, default templates from within the Synapse package will be used.
|
||||
#
|
||||
# Synapse will look for the following templates in this directory:
|
||||
#
|
||||
# * HTML page to prompt the user to choose an Identity Provider during
|
||||
# login: 'sso_login_idp_picker.html'.
|
||||
#
|
||||
# This is only used if multiple SSO Identity Providers are configured.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
# * redirect_url: the URL that the user will be redirected to after
|
||||
# login.
|
||||
#
|
||||
# * server_name: the homeserver's name.
|
||||
#
|
||||
# * providers: a list of available Identity Providers. Each element is
|
||||
# an object with the following attributes:
|
||||
#
|
||||
# * idp_id: unique identifier for the IdP
|
||||
# * idp_name: user-facing name for the IdP
|
||||
# * idp_icon: if specified in the IdP config, an MXC URI for an icon
|
||||
# for the IdP
|
||||
# * idp_brand: if specified in the IdP config, a textual identifier
|
||||
# for the brand of the IdP
|
||||
#
|
||||
# The rendered HTML page should contain a form which submits its results
|
||||
# back as a GET request, with the following query parameters:
|
||||
#
|
||||
# * redirectUrl: the client redirect URI (ie, the `redirect_url` passed
|
||||
# to the template)
|
||||
#
|
||||
# * idp: the 'idp_id' of the chosen IDP.
|
||||
#
|
||||
# * HTML page to prompt new users to enter a userid and confirm other
|
||||
# details: 'sso_auth_account_details.html'. This is only shown if the
|
||||
# SSO implementation (with any user_mapping_provider) does not return
|
||||
# a localpart.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
#
|
||||
# * server_name: the homeserver's name.
|
||||
#
|
||||
# * idp: details of the SSO Identity Provider that the user logged in
|
||||
# with: an object with the following attributes:
|
||||
#
|
||||
# * idp_id: unique identifier for the IdP
|
||||
# * idp_name: user-facing name for the IdP
|
||||
# * idp_icon: if specified in the IdP config, an MXC URI for an icon
|
||||
# for the IdP
|
||||
# * idp_brand: if specified in the IdP config, a textual identifier
|
||||
# for the brand of the IdP
|
||||
#
|
||||
# * user_attributes: an object containing details about the user that
|
||||
# we received from the IdP. May have the following attributes:
|
||||
#
|
||||
# * display_name: the user's display_name
|
||||
# * emails: a list of email addresses
|
||||
#
|
||||
# The template should render a form which submits the following fields:
|
||||
#
|
||||
# * username: the localpart of the user's chosen user id
|
||||
#
|
||||
# * HTML page allowing the user to consent to the server's terms and
|
||||
# conditions. This is only shown for new users, and only if
|
||||
# `user_consent.require_at_registration` is set.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
#
|
||||
# * server_name: the homeserver's name.
|
||||
#
|
||||
# * user_id: the user's matrix proposed ID.
|
||||
#
|
||||
# * user_profile.display_name: the user's proposed display name, if any.
|
||||
#
|
||||
# * consent_version: the version of the terms that the user will be
|
||||
# shown
|
||||
#
|
||||
# * terms_url: a link to the page showing the terms.
|
||||
#
|
||||
# The template should render a form which submits the following fields:
|
||||
#
|
||||
# * accepted_version: the version of the terms accepted by the user
|
||||
# (ie, 'consent_version' from the input variables).
|
||||
#
|
||||
# * HTML page for a confirmation step before redirecting back to the client
|
||||
# with the login token: 'sso_redirect_confirm.html'.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
#
|
||||
# * redirect_url: the URL the user is about to be redirected to.
|
||||
#
|
||||
# * display_url: the same as `redirect_url`, but with the query
|
||||
# parameters stripped. The intention is to have a
|
||||
# human-readable URL to show to users, not to use it as
|
||||
# the final address to redirect to.
|
||||
#
|
||||
# * server_name: the homeserver's name.
|
||||
#
|
||||
# * new_user: a boolean indicating whether this is the user's first time
|
||||
# logging in.
|
||||
#
|
||||
# * user_id: the user's matrix ID.
|
||||
#
|
||||
# * user_profile.avatar_url: an MXC URI for the user's avatar, if any.
|
||||
# None if the user has not set an avatar.
|
||||
#
|
||||
# * user_profile.display_name: the user's display name. None if the user
|
||||
# has not set a display name.
|
||||
#
|
||||
# * HTML page which notifies the user that they are authenticating to confirm
|
||||
# an operation on their account during the user interactive authentication
|
||||
# process: 'sso_auth_confirm.html'.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
# * redirect_url: the URL the user is about to be redirected to.
|
||||
#
|
||||
# * description: the operation which the user is being asked to confirm
|
||||
#
|
||||
# * idp: details of the Identity Provider that we will use to confirm
|
||||
# the user's identity: an object with the following attributes:
|
||||
#
|
||||
# * idp_id: unique identifier for the IdP
|
||||
# * idp_name: user-facing name for the IdP
|
||||
# * idp_icon: if specified in the IdP config, an MXC URI for an icon
|
||||
# for the IdP
|
||||
# * idp_brand: if specified in the IdP config, a textual identifier
|
||||
# for the brand of the IdP
|
||||
#
|
||||
# * HTML page shown after a successful user interactive authentication session:
|
||||
# 'sso_auth_success.html'.
|
||||
#
|
||||
# Note that this page must include the JavaScript which notifies of a successful authentication
|
||||
# (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
|
||||
#
|
||||
# This template has no additional variables.
|
||||
#
|
||||
# * HTML page shown after a user-interactive authentication session which
|
||||
# does not map correctly onto the expected user: 'sso_auth_bad_user.html'.
|
||||
#
|
||||
# When rendering, this template is given the following variables:
|
||||
# * server_name: the homeserver's name.
|
||||
# * user_id_to_verify: the MXID of the user that we are trying to
|
||||
# validate.
|
||||
#
|
||||
# * HTML page shown during single sign-on if a deactivated user (according to Synapse's database)
|
||||
# attempts to login: 'sso_account_deactivated.html'.
|
||||
#
|
||||
# This template has no additional variables.
|
||||
#
|
||||
# * HTML page to display to users if something goes wrong during the
|
||||
# OpenID Connect authentication process: 'sso_error.html'.
|
||||
#
|
||||
# When rendering, this template is given two variables:
|
||||
# * error: the technical name of the error
|
||||
# * error_description: a human-readable message for the error
|
||||
#
|
||||
# You can see the default templates at:
|
||||
# https://github.com/matrix-org/synapse/tree/master/synapse/res/templates
|
||||
#
|
||||
#template_dir: "res/templates"
|
||||
|
||||
|
||||
# JSON web token integration. The following settings can be used to make
|
||||
# Synapse JSON web tokens for authentication, instead of its internal
|
||||
@@ -5187,6 +5053,9 @@ ui_auth:
|
||||
|
||||
# Configuration for sending emails from Synapse.
|
||||
#
|
||||
# Server admins can configure custom templates for email content. See
|
||||
# https://matrix-org.github.io/synapse/latest/templates.html for more information.
|
||||
#
|
||||
email:
|
||||
# The hostname of the outgoing SMTP server to use. Defaults to 'localhost'.
|
||||
#
|
||||
@@ -5263,49 +5132,6 @@ email:
|
||||
#
|
||||
#invite_client_location: https://app.element.io
|
||||
|
||||
# Directory in which Synapse will try to find the template files below.
|
||||
# If not set, or the files named below are not found within the template
|
||||
# directory, default templates from within the Synapse package will be used.
|
||||
#
|
||||
# Synapse will look for the following templates in this directory:
|
||||
#
|
||||
# * The contents of email notifications of missed events: 'notif_mail.html' and
|
||||
# 'notif_mail.txt'.
|
||||
#
|
||||
# * The contents of account expiry notice emails: 'notice_expiry.html' and
|
||||
# 'notice_expiry.txt'.
|
||||
#
|
||||
# * The contents of password reset emails sent by the homeserver:
|
||||
# 'password_reset.html' and 'password_reset.txt'
|
||||
#
|
||||
# * An HTML page that a user will see when they follow the link in the password
|
||||
# reset email. The user will be asked to confirm the action before their
|
||||
# password is reset: 'password_reset_confirmation.html'
|
||||
#
|
||||
# * HTML pages for success and failure that a user will see when they confirm
|
||||
# the password reset flow using the page above: 'password_reset_success.html'
|
||||
# and 'password_reset_failure.html'
|
||||
#
|
||||
# * The contents of address verification emails sent during registration:
|
||||
# 'registration.html' and 'registration.txt'
|
||||
#
|
||||
# * HTML pages for success and failure that a user will see when they follow
|
||||
# the link in an address verification email sent during registration:
|
||||
# 'registration_success.html' and 'registration_failure.html'
|
||||
#
|
||||
# * The contents of address verification emails sent when an address is added
|
||||
# to a Matrix account: 'add_threepid.html' and 'add_threepid.txt'
|
||||
#
|
||||
# * HTML pages for success and failure that a user will see when they follow
|
||||
# the link in an address verification email sent when an address is added
|
||||
# to a Matrix account: 'add_threepid_success.html' and
|
||||
# 'add_threepid_failure.html'
|
||||
#
|
||||
# You can see the default templates at:
|
||||
# https://github.com/matrix-org/synapse/tree/master/synapse/res/templates
|
||||
#
|
||||
#template_dir: "res/templates"
|
||||
|
||||
# Subjects to use when sending emails from Synapse.
|
||||
#
|
||||
# The placeholder '%(app)s' will be replaced with the value of the 'app_name'
|
||||
@@ -5793,18 +5619,31 @@ handlers:
|
||||
backupCount: 3 # Does not include the current log file.
|
||||
encoding: utf8
|
||||
|
||||
# Default to buffering writes to log file for efficiency. This means that
|
||||
# will be a delay for INFO/DEBUG logs to get written, but WARNING/ERROR
|
||||
# logs will still be flushed immediately.
|
||||
# Default to buffering writes to log file for efficiency.
|
||||
# WARNING/ERROR logs will still be flushed immediately, but there will be a
|
||||
# delay (of up to `period` seconds, or until the buffer is full with
|
||||
# `capacity` messages) before INFO/DEBUG logs get written.
|
||||
buffer:
|
||||
class: logging.handlers.MemoryHandler
|
||||
class: synapse.logging.handlers.PeriodicallyFlushingMemoryHandler
|
||||
target: file
|
||||
# The capacity is the number of log lines that are buffered before
|
||||
# being written to disk. Increasing this will lead to better
|
||||
|
||||
# The capacity is the maximum number of log lines that are buffered
|
||||
# before being written to disk. Increasing this will lead to better
|
||||
# performance, at the expensive of it taking longer for log lines to
|
||||
# be written to disk.
|
||||
# This parameter is required.
|
||||
capacity: 10
|
||||
flushLevel: 30 # Flush for WARNING logs as well
|
||||
|
||||
# Logs with a level at or above the flush level will cause the buffer to
|
||||
# be flushed immediately.
|
||||
# Default value: 40 (ERROR)
|
||||
# Other values: 50 (CRITICAL), 30 (WARNING), 20 (INFO), 10 (DEBUG)
|
||||
flushLevel: 30 # Flush immediately for WARNING logs and higher
|
||||
|
||||
# The period of time, in seconds, between forced flushes.
|
||||
# Messages will not be delayed for longer than this time.
|
||||
# Default value: 5 seconds
|
||||
period: 5
|
||||
|
||||
# A handler that writes logs to stderr. Unused by default, but can be used
|
||||
# instead of "buffer" and "file" in the logger handlers.
|
||||
@@ -5979,6 +5818,276 @@ 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>
|
||||
<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>.
|
||||
Server admins can configure an additional directory for Synapse to look for templates
|
||||
in, allowing them to specify custom templates:</p>
|
||||
<pre><code class="language-yaml">templates:
|
||||
custom_templates_directory: /path/to/custom/templates/
|
||||
</code></pre>
|
||||
<p>If this setting is not set, or the files named below are not found within the directory,
|
||||
default templates from within the Synapse package will be used.</p>
|
||||
<p>Templates that are given variables when being rendered are rendered using <a href="https://jinja.palletsprojects.com/en/2.11.x/">Jinja 2</a>.
|
||||
Templates rendered by Jinja 2 can also access two functions on top of the functions
|
||||
already available as part of Jinja 2:</p>
|
||||
<pre><code class="language-python">format_ts(value: int, format: str) -> str
|
||||
</code></pre>
|
||||
<p>Formats a timestamp in milliseconds.</p>
|
||||
<p>Example: <code>reason.last_sent_ts|format_ts("%c")</code></p>
|
||||
<pre><code class="language-python">mxc_to_http(value: str, width: int, height: int, resize_method: str = "crop") -> str
|
||||
</code></pre>
|
||||
<p>Turns a <code>mxc://</code> URL for media content into an HTTP(S) one using the homeserver's
|
||||
<code>public_baseurl</code> configuration setting as the URL's base.</p>
|
||||
<p>Example: <code>message.sender_avatar_url|mxc_to_http(32,32)</code></p>
|
||||
<h2 id="email-templates"><a class="header" href="#email-templates">Email templates</a></h2>
|
||||
<p>Below are the templates Synapse will look for when generating the content of an email:</p>
|
||||
<ul>
|
||||
<li><code>notif_mail.html</code> and <code>notif_mail.txt</code>: The contents of email notifications of missed
|
||||
events.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>user_display_name</code>: the display name for the user receiving the notification</li>
|
||||
<li><code>unsubscribe_link</code>: the link users can click to unsubscribe from email notifications</li>
|
||||
<li><code>summary_text</code>: a summary of the notification(s). The text used can be customised
|
||||
by configuring the various settings in the <code>email.subjects</code> section of the
|
||||
configuration file.</li>
|
||||
<li><code>rooms</code>: a list of rooms containing events to include in the email. Each element is
|
||||
an object with the following attributes:
|
||||
<ul>
|
||||
<li><code>title</code>: a human-readable name for the room</li>
|
||||
<li><code>hash</code>: a hash of the ID of the room</li>
|
||||
<li><code>invite</code>: a boolean, which is <code>True</code> if the room is an invite the user hasn't
|
||||
accepted yet, <code>False</code> otherwise</li>
|
||||
<li><code>notifs</code>: a list of events, or an empty list if <code>invite</code> is <code>True</code>. Each element
|
||||
is an object with the following attributes:
|
||||
<ul>
|
||||
<li><code>link</code>: a <code>matrix.to</code> link to the event</li>
|
||||
<li><code>ts</code>: the time in milliseconds at which the event was received</li>
|
||||
<li><code>messages</code>: a list of messages containing one message before the event, the
|
||||
message in the event, and one message after the event. Each element is an
|
||||
object with the following attributes:
|
||||
<ul>
|
||||
<li><code>event_type</code>: the type of the event</li>
|
||||
<li><code>is_historical</code>: a boolean, which is <code>False</code> if the message is the one
|
||||
that triggered the notification, <code>True</code> otherwise</li>
|
||||
<li><code>id</code>: the ID of the event</li>
|
||||
<li><code>ts</code>: the time in milliseconds at which the event was sent</li>
|
||||
<li><code>sender_name</code>: the display name for the event's sender</li>
|
||||
<li><code>sender_avatar_url</code>: the avatar URL (as a <code>mxc://</code> URL) for the event's
|
||||
sender</li>
|
||||
<li><code>sender_hash</code>: a hash of the user ID of the sender</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>link</code>: a <code>matrix.to</code> link to the room</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>reason</code>: information on the event that triggered the email to be sent. It's an
|
||||
object with the following attributes:
|
||||
<ul>
|
||||
<li><code>room_id</code>: the ID of the room the event was sent in</li>
|
||||
<li><code>room_name</code>: a human-readable name for the room the event was sent in</li>
|
||||
<li><code>now</code>: the current time in milliseconds</li>
|
||||
<li><code>received_at</code>: the time in milliseconds at which the event was received</li>
|
||||
<li><code>delay_before_mail_ms</code>: the amount of time in milliseconds Synapse always waits
|
||||
before ever emailing about a notification (to give the user a chance to respond
|
||||
to other push or notice the window)</li>
|
||||
<li><code>last_sent_ts</code>: the time in milliseconds at which a notification was last sent
|
||||
for an event in this room</li>
|
||||
<li><code>throttle_ms</code>: the minimum amount of time in milliseconds between two
|
||||
notifications can be sent for this room</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>password_reset.html</code> and <code>password_reset.txt</code>: The contents of password reset emails
|
||||
sent by the homeserver.
|
||||
When rendering, these templates are given a <code>link</code> variable which contains the link the
|
||||
user must click in order to reset their password.</li>
|
||||
<li><code>registration.html</code> and <code>registration.txt</code>: The contents of address verification emails
|
||||
sent during registration.
|
||||
When rendering, these templates are given a <code>link</code> variable which contains the link the
|
||||
user must click in order to validate their email address.</li>
|
||||
<li><code>add_threepid.html</code> and <code>add_threepid.txt</code>: The contents of address verification emails
|
||||
sent when an address is added to a Matrix account.
|
||||
When rendering, these templates are given a <code>link</code> variable which contains the link the
|
||||
user must click in order to validate their email address.</li>
|
||||
</ul>
|
||||
<h2 id="html-page-templates-for-registration-and-password-reset"><a class="header" href="#html-page-templates-for-registration-and-password-reset">HTML page templates for registration and password reset</a></h2>
|
||||
<p>Below are the templates Synapse will look for when generating pages related to
|
||||
registration and password reset:</p>
|
||||
<ul>
|
||||
<li><code>password_reset_confirmation.html</code>: An HTML page that a user will see when they follow
|
||||
the link in the password reset email. The user will be asked to confirm the action
|
||||
before their password is reset.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>sid</code>: the session ID for the password reset</li>
|
||||
<li><code>token</code>: the token for the password reset</li>
|
||||
<li><code>client_secret</code>: the client secret for the password reset</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>password_reset_success.html</code> and <code>password_reset_failure.html</code>: HTML pages for success
|
||||
and failure that a user will see when they confirm the password reset flow using the
|
||||
page above.
|
||||
When rendering, <code>password_reset_success.html</code> is given no variable, and
|
||||
<code>password_reset_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
|
||||
for the password reset failure. </li>
|
||||
<li><code>registration_success.html</code> and <code>registration_failure.html</code>: HTML pages for success and
|
||||
failure that a user will see when they follow the link in an address verification email
|
||||
sent during registration.
|
||||
When rendering, <code>registration_success.html</code> is given no variable, and
|
||||
<code>registration_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
|
||||
for the registration failure.</li>
|
||||
<li><code>add_threepid_success.html</code> and <code>add_threepid_failure.html</code>: HTML pages for success and
|
||||
failure that a user will see when they follow the link in an address verification email
|
||||
sent when an address is added to a Matrix account.
|
||||
When rendering, <code>add_threepid_success.html</code> is given no variable, and
|
||||
<code>add_threepid_failure.html</code> is given a <code>failure_reason</code>, which contains the reason
|
||||
for the registration failure.</li>
|
||||
</ul>
|
||||
<h2 id="html-page-templates-for-single-sign-on-sso"><a class="header" href="#html-page-templates-for-single-sign-on-sso">HTML page templates for Single Sign-On (SSO)</a></h2>
|
||||
<p>Below are the templates Synapse will look for when generating pages related to SSO:</p>
|
||||
<ul>
|
||||
<li><code>sso_login_idp_picker.html</code>: HTML page to prompt the user to choose an
|
||||
Identity Provider during login.
|
||||
This is only used if multiple SSO Identity Providers are configured.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>redirect_url</code>: the URL that the user will be redirected to after
|
||||
login.</li>
|
||||
<li><code>server_name</code>: the homeserver's name.</li>
|
||||
<li><code>providers</code>: a list of available Identity Providers. Each element is
|
||||
an object with the following attributes:
|
||||
<ul>
|
||||
<li><code>idp_id</code>: unique identifier for the IdP</li>
|
||||
<li><code>idp_name</code>: user-facing name for the IdP</li>
|
||||
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
|
||||
for the IdP</li>
|
||||
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
|
||||
for the brand of the IdP
|
||||
The rendered HTML page should contain a form which submits its results
|
||||
back as a GET request, with the following query parameters:</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>redirectUrl</code>: the client redirect URI (ie, the <code>redirect_url</code> passed
|
||||
to the template)</li>
|
||||
<li><code>idp</code>: the 'idp_id' of the chosen IDP.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_auth_account_details.html</code>: HTML page to prompt new users to enter a
|
||||
userid and confirm other details. This is only shown if the
|
||||
SSO implementation (with any <code>user_mapping_provider</code>) does not return
|
||||
a localpart.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>server_name</code>: the homeserver's name.</li>
|
||||
<li><code>idp</code>: details of the SSO Identity Provider that the user logged in
|
||||
with: an object with the following attributes:
|
||||
<ul>
|
||||
<li><code>idp_id</code>: unique identifier for the IdP</li>
|
||||
<li><code>idp_name</code>: user-facing name for the IdP</li>
|
||||
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
|
||||
for the IdP</li>
|
||||
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
|
||||
for the brand of the IdP</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>user_attributes</code>: an object containing details about the user that
|
||||
we received from the IdP. May have the following attributes:
|
||||
<ul>
|
||||
<li>display_name: the user's display_name</li>
|
||||
<li>emails: a list of email addresses
|
||||
The template should render a form which submits the following fields:</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>username</code>: the localpart of the user's chosen user id</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_new_user_consent.html</code>: HTML page allowing the user to consent to the
|
||||
server's terms and conditions. This is only shown for new users, and only if
|
||||
<code>user_consent.require_at_registration</code> is set.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>server_name</code>: the homeserver's name.</li>
|
||||
<li><code>user_id</code>: the user's matrix proposed ID.</li>
|
||||
<li><code>user_profile.display_name</code>: the user's proposed display name, if any.</li>
|
||||
<li>consent_version: the version of the terms that the user will be
|
||||
shown</li>
|
||||
<li><code>terms_url</code>: a link to the page showing the terms.
|
||||
The template should render a form which submits the following fields:</li>
|
||||
<li><code>accepted_version</code>: the version of the terms accepted by the user
|
||||
(ie, 'consent_version' from the input variables).</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_redirect_confirm.html</code>: HTML page for a confirmation step before redirecting back
|
||||
to the client with the login token.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
|
||||
<li><code>display_url</code>: the same as <code>redirect_url</code>, but with the query
|
||||
parameters stripped. The intention is to have a
|
||||
human-readable URL to show to users, not to use it as
|
||||
the final address to redirect to.</li>
|
||||
<li><code>server_name</code>: the homeserver's name.</li>
|
||||
<li><code>new_user</code>: a boolean indicating whether this is the user's first time
|
||||
logging in.</li>
|
||||
<li><code>user_id</code>: the user's matrix ID.</li>
|
||||
<li><code>user_profile.avatar_url</code>: an MXC URI for the user's avatar, if any.
|
||||
<code>None</code> if the user has not set an avatar.</li>
|
||||
<li><code>user_profile.display_name</code>: the user's display name. <code>None</code> if the user
|
||||
has not set a display name.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_auth_confirm.html</code>: HTML page which notifies the user that they are authenticating
|
||||
to confirm an operation on their account during the user interactive authentication
|
||||
process.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>redirect_url</code>: the URL the user is about to be redirected to.</li>
|
||||
<li><code>description</code>: the operation which the user is being asked to confirm</li>
|
||||
<li><code>idp</code>: details of the Identity Provider that we will use to confirm
|
||||
the user's identity: an object with the following attributes:
|
||||
<ul>
|
||||
<li><code>idp_id</code>: unique identifier for the IdP</li>
|
||||
<li><code>idp_name</code>: user-facing name for the IdP</li>
|
||||
<li><code>idp_icon</code>: if specified in the IdP config, an MXC URI for an icon
|
||||
for the IdP</li>
|
||||
<li><code>idp_brand</code>: if specified in the IdP config, a textual identifier
|
||||
for the brand of the IdP</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_auth_success.html</code>: HTML page shown after a successful user interactive
|
||||
authentication session.
|
||||
Note that this page must include the JavaScript which notifies of a successful
|
||||
authentication (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
|
||||
This template has no additional variables.</li>
|
||||
<li><code>sso_auth_bad_user.html</code>: HTML page shown after a user-interactive authentication
|
||||
session which does not map correctly onto the expected user.
|
||||
When rendering, this template is given the following variables:
|
||||
<ul>
|
||||
<li><code>server_name</code>: the homeserver's name.</li>
|
||||
<li><code>user_id_to_verify</code>: the MXID of the user that we are trying to
|
||||
validate.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code>sso_account_deactivated.html</code>: HTML page shown during single sign-on if a deactivated
|
||||
user (according to Synapse's database) attempts to login.
|
||||
This template has no additional variables.</li>
|
||||
<li><code>sso_error.html</code>: HTML page to display to users if something goes wrong during the
|
||||
OpenID Connect authentication process.
|
||||
When rendering, this template is given two variables:
|
||||
<ul>
|
||||
<li><code>error</code>: the technical name of the error</li>
|
||||
<li><code>error_description</code>: a human-readable message for the error</li>
|
||||
</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>
|
||||
<p>Synapse supports multiple methods of authenticating users, either out-of-the-box or through custom pluggable
|
||||
authentication modules.</p>
|
||||
@@ -8160,6 +8269,7 @@ expressions:</p>
|
||||
^/_matrix/federation/v1/send/
|
||||
|
||||
# Client API requests
|
||||
^/_matrix/client/(api/v1|r0|unstable)/createRoom$
|
||||
^/_matrix/client/(api/v1|r0|unstable)/publicRooms$
|
||||
^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/joined_members$
|
||||
^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/context/.*$
|
||||
@@ -8325,10 +8435,12 @@ For example:</p>
|
||||
^/_synapse/admin/v1/user/.*/media.*$
|
||||
^/_synapse/admin/v1/media/.*$
|
||||
^/_synapse/admin/v1/quarantine_media/.*$
|
||||
^/_synapse/admin/v1/users/.*/media$
|
||||
</code></pre>
|
||||
<p>You should also set <code>enable_media_repo: False</code> in the shared configuration
|
||||
file to stop the main synapse running background jobs related to managing the
|
||||
media repository.</p>
|
||||
media repository. Note that doing so will prevent the main process from being
|
||||
able to handle the above endpoints.</p>
|
||||
<p>In the <code>media_repository</code> worker configuration file, configure the http listener to
|
||||
expose the <code>media</code> resource. For example:</p>
|
||||
<pre><code class="language-yaml"> worker_listeners:
|
||||
|
||||
Reference in new issue
Block a user