From 66dc75ec0555669b38b5446df40ddadcd76ef70c Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Wed, 14 Sep 2022 20:25:14 +0000 Subject: deploy: 80bb098d8775cc2ad1bf5abd150913577e643481 --- latest/print.html | 473 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 318 insertions(+), 155 deletions(-) (limited to 'latest/print.html') diff --git a/latest/print.html b/latest/print.html index 717f3b5c25..b0a7e87299 100644 --- a/latest/print.html +++ b/latest/print.html @@ -77,7 +77,7 @@ @@ -583,8 +583,12 @@ and notif_from fields filled out. You may also need to set s

If email is not configured, password reset, registration and notifications via email will be disabled.

Registering a user

-

The easiest way to create a new user is to do so from a client like Element.

-

Alternatively, you can do so from the command line. This can be done as follows:

+

One way to create a new user is to do so from a client like +Element. This requires registration to be enabled via +the +enable_registration +setting.

+

Alternatively, you can create new users from the command line. This can be done as follows:

  1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was installed via a prebuilt package, register_new_matrix_user should already be @@ -595,7 +599,7 @@ synctl start # if not already running
  2. Run the following command: -
    register_new_matrix_user -c homeserver.yaml http://localhost:8008
+
    register_new_matrix_user -c homeserver.yaml
@@ -607,12 +611,13 @@ Confirm password: Make admin [no]: Success! -

This process uses a setting registration_shared_secret in -homeserver.yaml, which is shared between Synapse itself and the -register_new_matrix_user script. It doesn't matter what it is (a random -value is generated by --generate-config), but it should be kept secret, as -anyone with knowledge of it can register users, including admin accounts, -on your server even if enable_registration is false.

+

This process uses a setting +registration_shared_secret, +which is shared between Synapse itself and the register_new_matrix_user +script. It doesn't matter what it is (a random value is generated by +--generate-config), but it should be kept secret, as anyone with knowledge of +it can register users, including admin accounts, on your server even if +enable_registration is false.

Setting up a TURN server

For reliable VoIP calls to be routed via this homeserver, you MUST configure a TURN server. See TURN setup for details.

@@ -1612,6 +1617,37 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb +

Upgrading to v1.67.0

+

Direct TCP replication is no longer supported: migrate to Redis

+

Redis support was added in v1.13.0 with it becoming the recommended method in +v1.18.0. It replaced the old direct TCP connections (which was deprecated as of +v1.18.0) to the main process. With Redis, rather than all the workers connecting +to the main process, all the workers and the main process connect to Redis, +which relays replication commands between processes. This can give a significant +CPU saving on the main process and is a prerequisite for upcoming +performance improvements.

+

To migrate to Redis add the redis config, +and remove the TCP replication listener from config of the master and +worker_replication_port from worker config. Note that a HTTP listener with a +replication resource is still required.

+

Minimum version of Poetry is now v1.2.0

+

The minimum supported version of poetry is now 1.2. This should only affect +those installing from a source checkout.

+

Rust requirement in the next release

+

From the next major release (v1.68.0) installing Synapse from a source checkout +will require a recent Rust compiler. Those using packages or +pip install matrix-synapse will not be affected.

+

The simplest way of installing Rust is via rustup.rs

+

SQLite version requirement in the next release

+

From the next major release (v1.68.0) Synapse will require SQLite 3.27.0 or +higher. Synapse v1.67.0 will be the last major release supporting SQLite +versions 3.22 to 3.26.

+

Those using docker images or Debian packages from Matrix.org will not be +affected. If you have installed from source, you should check the version of +SQLite used by Python with:

+
python -c "import sqlite3; print(sqlite3.sqlite_version)"
+
+

If this is too old, refer to your distribution for advice on upgrading.

Upgrading to v1.66.0

Delegation of email validation no longer supported

As of this version, Synapse no longer allows the tasks of verifying email address @@ -3496,9 +3532,6 @@ configuration.

  • metrics: (see the docs here),

    • -
  • -

    replication: (deprecated as of Synapse 1.18, see the docs here).

    -
  • @@ -3660,6 +3693,7 @@ hs_disabled_message: 'Reason for why the HS is blocked' server owner wants to limit to the number of monthly active users. When enabled and a limit is reached the server returns a ResourceLimitError with error type Codes.RESOURCE_LIMIT_EXCEEDED. Defaults to false. If this is enabled, a value for max_mau_value must also be set.

    +

    See Monthly Active Users for details on how to configure MAU.

    Example configuration:

    limit_usage_by_mau: true
    @@ -4728,23 +4762,25 @@ should be in the form of providers.json). By default this list is empty.

    See here for full details on setting up captcha.

    recaptcha_public_key

    -

    This homeserver's ReCAPTCHA public key. Must be specified if enable_registration_captcha is -enabled.

    +

    This homeserver's ReCAPTCHA public key. Must be specified if +enable_registration_captcha is enabled.

    Example configuration:

    recaptcha_public_key: "YOUR_PUBLIC_KEY"

    recaptcha_private_key

    -

    This homeserver's ReCAPTCHA private key. Must be specified if enable_registration_captcha is +

    This homeserver's ReCAPTCHA private key. Must be specified if +enable_registration_captcha is enabled.

    Example configuration:

    recaptcha_private_key: "YOUR_PRIVATE_KEY"

    enable_registration_captcha

    -

    Set to true to enable ReCaptcha checks when registering, preventing signup -unless a captcha is answered. Requires a valid ReCaptcha public/private key. -Defaults to false.

    +

    Set to true to require users to complete a CAPTCHA test when registering an account. +Requires a valid ReCaptcha public/private key. +Defaults to false.

    +

    Note that enable_registration must also be set to allow account registration.

    Example configuration:

    enable_registration_captcha: true
    @@ -4796,69 +4832,34 @@ it allows users to connect to arbitrary endpoints without having first signed up

    Registration can be rate-limited using the parameters in the Ratelimiting section of this manual.

    enable_registration

    -

    Enable registration for new users. Defaults to false. It is highly recommended that if you enable registration, -you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration -without any verification, you must also set enable_registration_without_verification to true.

    +

    Enable registration for new users. Defaults to false.

    +

    It is highly recommended that if you enable registration, you set one or more +or the following options, to avoid abuse of your server by "bots":

    + +

    (In order to enable registration without any verification, you must also set +enable_registration_without_verification.)

    +

    Note that even if this setting is disabled, new accounts can still be created +via the admin API if +registration_shared_secret is set.

    Example configuration:

    enable_registration: true

    enable_registration_without_verification

    Enable registration without email or captcha verification. Note: this option is not recommended, -as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect -unless enable_registration is also enabled.

    +as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect +unless enable_registration is also enabled.

    Example configuration:

    enable_registration_without_verification: true
    -

    session_lifetime

    -

    Time that a user's session remains valid for, after they log in.

    -

    Note that this is not currently compatible with guest logins.

    -

    Note also that this is calculated at login time: changes are not applied retrospectively to users who have already -logged in.

    -

    By default, this is infinite.

    -

    Example configuration:

    -
    session_lifetime: 24h
-
    -
    -

    refresh_access_token_lifetime

    -

    Time that an access token remains valid for, if the session is using refresh tokens.

    -

    For more information about refresh tokens, please see the manual.

    -

    Note that this only applies to clients which advertise support for refresh tokens.

    -

    Note also that this is calculated at login time and refresh time: changes are not applied to -existing sessions until they are refreshed.

    -

    By default, this is 5 minutes.

    -

    Example configuration:

    -
    refreshable_access_token_lifetime: 10m
-
    -
    -

    refresh_token_lifetime: 24h

    -

    Time that a refresh token remains valid for (provided that it is not -exchanged for another one first). -This option can be used to automatically log-out inactive sessions. -Please see the manual for more information.

    -

    Note also that this is calculated at login time and refresh time: -changes are not applied to existing sessions until they are refreshed.

    -

    By default, this is infinite.

    -

    Example configuration:

    -
    refresh_token_lifetime: 24h
-
    -
    -

    nonrefreshable_access_token_lifetime

    -

    Time that an access token remains valid for, if the session is NOT -using refresh tokens.

    -

    Please note that not all clients support refresh tokens, so setting -this to a short value may be inconvenient for some users who will -then be logged out frequently.

    -

    Note also that this is calculated at login time: changes are not applied -retrospectively to existing sessions for users that have already logged in.

    -

    By default, this is infinite.

    -

    Example configuration:

    -
    nonrefreshable_access_token_lifetime: 24h
-
    -

    registrations_require_3pid

    -

    If this is set, the user must provide all of the specified types of 3PID when registering.

    +

    If this is set, users must provide all of the specified types of 3PID when registering an account.

    +

    Note that enable_registration must also be set to allow account registration.

    Example configuration:

    registrations_require_3pid:
   - email
@@ -4894,20 +4895,36 @@ flow (overrides registrations_require_3pid if MSISDNs are set as re
 
    registration_requires_token
    
 
    Require users to submit a token during registration.
 Tokens can be managed using the admin API.
-Note that enable_registration must be set to true.
 Disabling this option will not delete any tokens previously generated.
-Defaults to false. Set to true to enable.
    
+Defaults to false. Set to true to enable.
    
+
    Note that enable_registration must also be set to allow account registration.
    
 
    Example configuration:
    
 
    registration_requires_token: true
 
    
 
    
 
    registration_shared_secret
    
-
    If set, allows registration of standard or admin accounts by anyone who
-has the shared secret, even if registration is otherwise disabled.
    
+
    If set, allows registration of standard or admin accounts by anyone who has the
+shared secret, even if enable_registration is not
+set.
    
+
    This is primarily intended for use with the register_new_matrix_user script
+(see Registering a user);
+however, the interface is documented.
    
+
    See also registration_shared_secret_path.
    
 
    Example configuration:
    
 
    registration_shared_secret: <PRIVATE STRING>
 
    
 
    
+
    registration_shared_secret_path
    
+
    An alternative to registration_shared_secret:
+allows the shared secret to be specified in an external file.
    
+
    The file should be a plain text file, containing only the shared secret.
    
+
    If this file does not exist, Synapse will create a new signing
+key on startup and store it in this file.
    
+
    Example configuration:
    
+
    registration_shared_secret_file: /path/to/secrets/file
+
    
+
    Added in Synapse 1.67.0.
    
+
    
 
    bcrypt_rounds
    
 
    Set the number of bcrypt rounds used to generate password hash.
 Larger numbers increase the work factor needed to generate the hash.
@@ -5075,6 +5092,54 @@ raise an error if the registration completes and the username conflicts.
    
 
    inhibit_user_in_use_error: true
 
    
 
    
+
    User session management
    
+
    
+
    session_lifetime
    
+
    Time that a user's session remains valid for, after they log in.
    
+
    Note that this is not currently compatible with guest logins.
    
+
    Note also that this is calculated at login time: changes are not applied retrospectively to users who have already
+logged in.
    
+
    By default, this is infinite.
    
+
    Example configuration:
    
+
    session_lifetime: 24h
+
    
+
    
+
    refresh_access_token_lifetime
    
+
    Time that an access token remains valid for, if the session is using refresh tokens.
    
+
    For more information about refresh tokens, please see the manual.
    
+
    Note that this only applies to clients which advertise support for refresh tokens.
    
+
    Note also that this is calculated at login time and refresh time: changes are not applied to
+existing sessions until they are refreshed.
    
+
    By default, this is 5 minutes.
    
+
    Example configuration:
    
+
    refreshable_access_token_lifetime: 10m
+
    
+
    
+
    refresh_token_lifetime: 24h
    
+
    Time that a refresh token remains valid for (provided that it is not
+exchanged for another one first).
+This option can be used to automatically log-out inactive sessions.
+Please see the manual for more information.
    
+
    Note also that this is calculated at login time and refresh time:
+changes are not applied to existing sessions until they are refreshed.
    
+
    By default, this is infinite.
    
+
    Example configuration:
    
+
    refresh_token_lifetime: 24h
+
    
+
    
+
    nonrefreshable_access_token_lifetime
    
+
    Time that an access token remains valid for, if the session is NOT
+using refresh tokens.
    
+
    Please note that not all clients support refresh tokens, so setting
+this to a short value may be inconvenient for some users who will
+then be logged out frequently.
    
+
    Note also that this is calculated at login time: changes are not applied
+retrospectively to existing sessions for users that have already logged in.
    
+
    By default, this is infinite.
    
+
    Example configuration:
    
+
    nonrefreshable_access_token_lifetime: 24h
+
    
+
    
 
    Metrics
    
 
    Config options related to metrics.
    
 
    
@@ -5132,7 +5197,7 @@ Defaults to https://matrix.org/report-usage-stats/push
    
 
    API Configuration
    
 
    Config settings related to the client/server API
    
 
    
-
    room_prejoin_state:
    
+
    room_prejoin_state
    
 
    Controls for the state that is shared with users who receive an invite
 to a room. By default, the following state event types are shared with users who
 receive invites to the room:
    
@@ -5216,7 +5281,9 @@ forms to work.
    
 
    Config options relating to signing keys
    
 
    
 
    signing_key_path
    
-
    Path to the signing key to sign messages with.
    
+
    Path to the signing key to sign events and federation requests with.
    
+
    New in Synapse 1.67: If this file does not exist, Synapse will create a new signing
+key on startup and store it in this file.
    
 
    Example configuration:
    
 
    signing_key_path: "CONFDIR/SERVERNAME.signing.key"
 
    
@@ -5242,7 +5309,7 @@ are still valid. Defaults to 1d.
    
 
    key_refresh_interval: 2d
 
    
 
    
-
    trusted_key_servers:
    
+
    trusted_key_servers
    
 
    The trusted servers to download signing keys from.
    
 
    When we need to fetch a signing key, each server is tried in parallel.
    
 
    Normally, the connection to the key server is validated via TLS certificates.
@@ -5296,14 +5363,12 @@ defaults to the server signing key.
    
 
    Single sign-on integration
    
 
    The following settings can be used to make Synapse use a single sign-on
 provider for authentication, instead of its internal password database.
    
-
    You will probably also want to set the following options to false to
+
    You will probably also want to set the following options to false to
 disable the regular login/registration flows:
    
 
-
    You will also want to investigate the settings under the "sso" configuration
-section below.
    
 
    
 
    saml2_config
    
 
    Enable SAML2 for registration and login. Uses pysaml2. To learn more about pysaml and
@@ -7003,7 +7068,8 @@ to install Dex.
    
 
    Set the Allowed Callback URLs to [synapse public baseurl]/_synapse/client/oidc/callback
  • -

    Add a rule to add the preferred_username claim.

    +

    Add a rule with any name to add the preferred_username claim. +(See https://auth0.com/docs/customize/rules/create-rules for more information on how to create rules.)

    Code sample 
    function addPersistenceAttribute(user, context, callback) {
@@ -9641,13 +9707,8 @@ sync with the database state.
    
 stream between all configured Synapse processes. Additionally, processes may
 make HTTP requests to each other, primarily for operations which need to wait
 for a reply ─ such as sending an event.
    
-
    Redis support was added in v1.13.0 with it becoming the recommended method in
-v1.18.0. It replaced the old direct TCP connections (which is deprecated as of
-v1.18.0) to the main process. With Redis, rather than all the workers connecting
-to the main process, all the workers and the main process connect to Redis,
-which relays replication commands between processes. This can give a significant
-cpu saving on the main process and will be a prerequisite for upcoming
-performance improvements.
    
+
    All the workers and the main process connect to Redis, which relays replication
+commands between processes.
    
 
    If Redis support is enabled Synapse will use it as a shared cache, as well as a
 pub/sub mechanism.
    
 
    See the Architectural diagram section at the end for
@@ -9704,19 +9765,25 @@ worker_replication_secret: ""
 redis:
     enabled: true
    -

    See the sample config for the full documentation of each option.

    +

    See the configuration manual for the full documentation of each option.

    Under no circumstances should the replication listener be exposed to the -public internet; it has no authentication and is unencrypted.

    +public internet; replication traffic is:

    +
      +
    • always unencrypted
      • +
    • unauthenticated, unless worker_replication_secret is configured
      • +

    Worker configuration

    -

    In the config file for each worker, you must specify the type of worker -application (worker_app), and you should specify a unique name for the worker -(worker_name). The currently available worker applications are listed below. -You must also specify the HTTP replication endpoint that it should talk to on -the main synapse process. worker_replication_host should specify the host of -the main synapse and worker_replication_http_port should point to the HTTP -replication port. If the worker will handle HTTP requests then the -worker_listeners option should be set with a http listener, in the same way -as the listeners option in the shared config.

    +

    In the config file for each worker, you must specify:

    +
      +
    • The type of worker (worker_app). The currently available worker applications are listed below.
      • +
    • A unique name for the worker (worker_name).
      • +
    • The HTTP replication endpoint that it should talk to on the main synapse process +(worker_replication_host and worker_replication_http_port)
      • +
    • If handling HTTP requests, a worker_listeners option with an http +listener, in the same way as the listeners option in the shared config.
      • +
    • If handling the ^/_matrix/client/v3/keys/upload endpoint, the HTTP URI for +the main process (worker_main_http_uri).
      • +

    For example:

    worker_app: synapse.app.generic_worker
 worker_name: generic_worker1
@@ -9725,6 +9792,8 @@ worker_name: generic_worker1
 worker_replication_host: 127.0.0.1
 worker_replication_http_port: 9093
 
+worker_main_http_uri: http://localhost:8008/
+
 worker_listeners:
   - type: http
     port: 8083
@@ -9800,10 +9869,12 @@ information.
    
 ^/_matrix/client/(api/v1|r0|v3|unstable)/search$
 
 # Encryption requests
+# Note that ^/_matrix/client/(r0|v3|unstable)/keys/upload/ requires `worker_main_http_uri`
 ^/_matrix/client/(r0|v3|unstable)/keys/query$
 ^/_matrix/client/(r0|v3|unstable)/keys/changes$
 ^/_matrix/client/(r0|v3|unstable)/keys/claim$
 ^/_matrix/client/(r0|v3|unstable)/room_keys/
+^/_matrix/client/(r0|v3|unstable)/keys/upload/
 
 # Registration/login requests
 ^/_matrix/client/(api/v1|r0|v3|unstable)/login$
@@ -9894,8 +9965,7 @@ of events, then a dedicated set of workers can be provisioned to limit the
 effects of bursts of events from that bridge on events sent by normal users.
    
 
    Stream writers
    
 
    Additionally, the writing of specific streams (such as events) can be moved off
-of the main process to a particular worker.
-(This is only supported with Redis-based replication.)
    
+of the main process to a particular worker.
    
 
    To enable this, the worker must have a HTTP replication listener configured,
 have a worker_name and be listed in the instance_map config. The same worker
 can handle multiple streams, but unless otherwise documented, each stream can only
@@ -10097,40 +10167,20 @@ endpoint as long as either this worker or the main process are configured to
 handle it, and are online.
    
 
    If update_user_directory is set to false, and this worker is not running,
 the above endpoint may give outdated results.
    
-
    synapse.app.frontend_proxy
    
-
    Proxies some frequently-requested client endpoints to add caching and remove
-load from the main synapse. It can handle REST endpoints matching the following
-regular expressions:
    
-
    ^/_matrix/client/(r0|v3|unstable)/keys/upload
-
    
-
    If use_presence is False in the homeserver config, it can also handle REST
-endpoints matching the following regular expressions:
    
-
    ^/_matrix/client/(api/v1|r0|v3|unstable)/presence/[^/]+/status
-
    
-
    This "stub" presence handler will pass through GET request but make the
-PUT effectively a no-op.
    
-
    It will proxy any requests it cannot handle to the main synapse instance. It
-must therefore be configured with the location of the main instance, via
-the worker_main_http_uri setting in the frontend_proxy worker configuration
-file. For example:
    
-
    worker_main_http_uri: http://127.0.0.1:8008
-
    
 
    Historical apps
    
-
    Note: Historically there used to be more apps, however they have been
-amalgamated into a single synapse.app.generic_worker app. The remaining apps
-are ones that do specific processing unrelated to requests, e.g. the pusher
-that handles sending out push notifications for new events. The intention is for
-all these to be folded into the generic_worker app and to use config to define
-which processes handle the various proccessing such as push notifications.
    
+
    The following used to be separate worker application types, but are now
+equivalent to synapse.app.generic_worker:
    
+
      
+
    • synapse.app.client_reader
      • 
+
    • synapse.app.event_creator
      • 
+
    • synapse.app.federation_reader
      • 
+
    • synapse.app.frontend_proxy
      • 
+
    • synapse.app.synchrotron
      • 
+
    
 
    Migration from old config
    
-
    There are two main independent changes that have been made: introducing Redis
-support and merging apps into synapse.app.generic_worker. Both these changes
-are backwards compatible and so no changes to the config are required, however
-server admins are encouraged to plan to migrate to Redis as the old style direct
-TCP replication config is deprecated.
    
-
    To migrate to Redis add the redis config as above, and optionally remove the
-TCP replication listener from master and worker_replication_port from worker
-config.
    
+
    A main change that has occurred is the merging of worker apps into
+synapse.app.generic_worker. This change is backwards compatible and so no
+changes to the config are required.
    
 
    To migrate apps to use synapse.app.generic_worker simply update the
 worker_app option in the worker configs, and where worker are started (e.g.
 in systemd service files, but not required for synctl).
    
@@ -10210,6 +10260,8 @@ worker_name: generic_worker1
 worker_replication_host: 127.0.0.1
 worker_replication_http_port: 9093
 
+worker_main_http_uri: http://localhost:8008/
+
 worker_listeners:
   - type: http
     port: 8083
@@ -10840,9 +10892,9 @@ a purge id:
    
 non-interactive way. This is generally used for bootstrapping a Synapse
 instance with administrator accounts.
    
 
    To authenticate yourself to the server, you will need both the shared secret
-(registration_shared_secret in the homeserver configuration), and a
-one-time nonce. If the registration shared secret is not configured, this API
-is not enabled.
    
+(registration_shared_secret
+in the homeserver configuration), and a one-time nonce. If the registration
+shared secret is not configured, this API is not enabled.
    
 
    To fetch the nonce, you need to request one from the API:
    
 
    > GET /_synapse/admin/v1/register
 
@@ -13360,7 +13412,13 @@ parts of the process.

  • Enable Synapse metrics:

    -

    There are two methods of enabling metrics in Synapse.

    +

    In homeserver.yaml, make sure enable_metrics is +set to True.

    +
    • +
  • +

    Enable the /_synapse/metrics Synapse endpoint that Prometheus uses to +collect data:

    +

    There are two methods of enabling the metrics endpoint in Synapse.

    The first serves the metrics as a part of the usual web server and can be enabled by adding the "metrics" resource to the existing listener as such:

    @@ -13385,8 +13443,6 @@ over HTTP only, and will be available at /_synapse/metrics.

    bind_addresses: - '0.0.0.0'     -

    For both options, you will need to ensure that enable_metrics is -set to True.

  • Restart Synapse.

    @@ -13665,6 +13721,70 @@ consider using one of the following known implementations:

  • Matrix.org's Panopticon
  • Famedly's Barad-dûr
    • +

    Monthly Active Users

    +

    Synapse can be configured to record the number of monthly active users (also referred to as MAU) on a given homeserver. +For clarity's sake, MAU only tracks local users.

    +

    Please note that the metrics recorded by the Homeserver Usage Stats +are calculated differently. The monthly_active_users from the usage stats does not take into account any +of the rules below, and counts any users who have made a request to the homeserver in the last 30 days.

    +

    See the configuration manual for details on how to configure MAU.

    +

    Calculating active users

    +

    Individual user activity is measured in active days. If a user performs an action, the exact time of that action is then recorded. When +calculating the MAU figure, any users with a recorded action in the last 30 days are considered part of the cohort. Days are measured +as a rolling window from the current system time to 30 days ago.

    +

    So for example, if Synapse were to calculate the active users on the 15th July at 13:25, it would include any activity from 15th June 13:25 onwards.

    +

    A user is never considered active if they are either:

    +
      +
    • Part of the trial day cohort (described below)
      • +
    • Owned by an application service. +
        +
      • Note: This only covers users that are part of an application service namespaces.users registration. The namespace +must also be marked as exclusive.
        • +
      +
      • +
    +

    Otherwise, any request to Synapse will mark the user as active. Please note that registration will not mark a user as active unless +they register with a 3pid that is included in the config field mau_limits_reserved_threepids.

    +

    The Prometheus metric for MAU is refreshed every 5 minutes.

    +

    Once an hour, Synapse checks to see if any users are inactive (with only activity timestamps later than 30 days). These users +are removed from the active users cohort. If they then become active, they are immediately restored to the cohort.

    +

    It is important to note that deactivated users are not immediately removed from the pool of active users, but as these users won't +perform actions they will eventually be removed from the cohort.

    +

    Trial days

    +

    If the config option mau_trial_days is set, a user must have been active this many days after registration to be active. A user is in the +trial period if their registration timestamp (also known as the creation_ts) is less than mau_trial_days old.

    +

    As an example, if mau_trial_days is set to 3 and a user is active after 3 days (72 hours from registration time) then they will be counted as active.

    +

    The mau_appservice_trial_days config further extends this rule by applying different durations depending on the appservice_id of the user. +Users registered by an application service will be recorded with an appservice_id matching the id key in the registration file for that service.

    +

    Limiting usage of the homeserver when the maximum MAU is reached

    +

    If both config options limit_usage_by_mau and max_mau_value is set, and the current MAU value exceeds the maximum value, the +homeserver will begin to block some actions.

    +

    Individual users matching any of the below criteria never have their actions blocked:

    +
      +
    • Considered part of the cohort of MAU users.
      • +
    • Considered part of the trial period.
      • +
    • Registered as a support user.
      • +
    • Application service users if track_appservice_user_ips is NOT set.
      • +
    +

    Please not that server admins are not exempt from blocking.

    +

    The following actions are blocked when the MAU limit is exceeded:

    +
      +
    • Logging in
      • +
    • Sending events
      • +
    • Creating rooms
      • +
    • Syncing
      • +
    +

    Registration is also blocked for all new signups unless the user is registering with a threepid included in the mau_limits_reserved_threepids +config value.

    +

    When a request is blocked, the response will have the errcode M_RESOURCE_LIMIT_EXCEEDED.

    +

    Metrics

    +

    Synapse records several different prometheus metrics for MAU.

    +

    synapse_admin_mau:current records the current MAU figure for native (non-application-service) users.

    +

    synapse_admin_mau:max records the maximum MAU as dictated by the max_mau_value config value.

    +

    synapse_admin_mau_current_mau_by_service records the current MAU including application service users. The label app_service can be used +to filter by a specific service ID. This also includes non-application-service users under app_service=native .

    +

    synapse_admin_mau:registered_reserved_users records the number of users specified in mau_limits_reserved_threepids which have +registered accounts on the homeserver.

    Understanding Synapse through Grafana graphs

    It is possible to monitor much of the internal state of Synapse using Prometheus metrics and Grafana. @@ -14109,6 +14229,7 @@ pipx install poetry

    but see poetry's installation instructions for other installation methods.

    +

    Synapse requires Poetry version 1.2.0 or later.

    Next, open a terminal and install dependencies as follows:

    cd path/where/you/have/cloned/the/repository
 poetry install --extras all
@@ -15053,6 +15174,22 @@ default value is the string "FALSE" - wh
 in Python, evaluates to True.
    
 
 
+
    event_id global uniqueness
    
+
    In room versions 1 and 2 it's possible to end up with two events with the
+same event_id (in the same or different rooms). After room version 3, that
+can only happen with a hash collision, which we basically hope will never
+happen.
    
+
    There are several places in Synapse and even Matrix APIs like GET /_matrix/federation/v1/event/{eventId}
+where we assume that event IDs are globally unique.
    
+
    But hash collisions are still possible, and by treating event IDs as room
+scoped, we can reduce the possibility of a hash collision. When scoping
+event_id in the database schema, it should be also accompanied by room_id
+(PRIMARY KEY (room_id, event_id)) and lookups should be done through the pair
+(room_id, event_id).
    
+
    There has been a lot of debate on this in places like
+https://github.com/matrix-org/matrix-spec-proposals/issues/2779 and
+MSC2848 which
+has no resolution yet (as of 2022-09-01).
    
 
    Implementing experimental features in Synapse
    
 
    It can be desirable to implement "experimental" features which are disabled by
 default and must be explicitly enabled via the Synapse configuration. This is
@@ -15263,11 +15400,7 @@ doesn't require poetry. (It's what we use in CI too). However, you could try
 poetry build too.
    
 
    Troubleshooting
    
 
    Check the version of poetry with poetry --version.
    
-
    At the time of writing, the 1.2 series is beta only. We have seen some examples
-where the lockfiles generated by 1.2 prereleasese aren't interpreted correctly
-by poetry 1.1.x. For now, use poetry 1.1.14, which includes a critical
-change needed to remain
-compatible with PyPI.
    
+
    The minimum version of poetry supported by Synapse is 1.2.
    
 
    It can also be useful to check the version of poetry-core in use. If you've
 installed poetry with pipx, try pipx runpip poetry list | grep poetry-core.
    
 
    Clear caches: poetry cache clear --all pypi.
    
@@ -16370,13 +16503,42 @@ used if we don't have a chain cover index for the room (e.g. because we're in
 the process of indexing it).
    
 
    Chain Cover Index
    
 
    Synapse computes auth chain differences by pre-computing a "chain cover" index
-for the auth chain in a room, allowing efficient reachability queries like "is
-event A in the auth chain of event B". This is done by assigning every event a
-chain ID and sequence number (e.g. (5,3)), and having a map of links
-between chains (e.g. (5,3) -> (2,4)) such that A is reachable by B (i.e. A
-is in the auth chain of B) if and only if either:
    
+for the auth chain in a room, allowing us to efficiently make reachability queries
+like "is event A in the auth chain of event B?". We could do this with an index
+that tracks all pairs (A, B) such that A is in the auth chain of B. However, this
+would be prohibitively large, scaling poorly as the room accumulates more state
+events.
    
+
    Instead, we break down the graph into chains. A chain is a subset of a DAG
+with the following property: for any pair of events E and F in the chain,
+the chain contains a path E -> F or a path F -> E. This forces a chain to be
+linear (without forks), e.g. E -> F -> G -> ... -> H. Each event in the chain
+is given a sequence number local to that chain. The oldest event E in the
+chain has sequence number 1. If E has a child F in the chain, then F has
+sequence number 2. If E has a grandchild G in the chain, then G has
+sequence number 3; and so on.
    
+
    Synapse ensures that each persisted event belongs to exactly one chain, and
+tracks how the chains are connected to one another. This allows us to
+efficiently answer reachability queries. Doing so uses less storage than
+tracking reachability on an event-by-event basis, particularly when we have
+fewer and longer chains. See
    
+
    
+
    Jagadish, H. (1990). A compression technique to materialize transitive closure.
+ACM Transactions on Database Systems (TODS), 15*(4)*, 558-598.
    
+
    
+
    for the original idea or
    
+
    
+
    Y. Chen, Y. Chen, An efficient algorithm for answering graph
+reachability queries,
+in: 2008 IEEE 24th International Conference on Data Engineering, April 2008,
+pp. 893–902. (PDF available via Google Scholar.)
    
+
    
+
    for a more modern take.
    
+
    In practical terms, the chain cover assigns every event a
+chain ID and sequence number (e.g. (5,3)), and maintains a map of links
+between events in chains (e.g. (5,3) -> (2,4)) such that A is reachable by B
+(i.e. A is in the auth chain of B) if and only if either:
    
 
      
-
    1. A and B have the same chain ID and A's sequence number is less than B's
+
    2. A and B have the same chain ID and A's sequence number is less than B's
 sequence number; or
      3. 
 
    3. there is a link L between B's chain ID and A's chain ID such that
 L.start_seq_no <= B.seq_no and A.seq_no <= L.end_seq_no.
      4. 
@@ -16385,8 +16547,9 @@ sequence number; or
 each chain to every other reachable chain (the transitive closure of the links
 graph), and one where we remove redundant links (the transitive reduction of the
 links graph) e.g. if we have chains C3 -> C2 -> C1 then the link C3 -> C1
-would not be stored. Synapse uses the former implementations so that it doesn't
-need to recurse to test reachability between chains.
      
+would not be stored. Synapse uses the former implementation so that it doesn't
+need to recurse to test reachability between chains. This trades-off extra storage
+in order to save CPU cycles and DB queries.
      
 
      Example
      
 
      An example auth graph would look like the following, where chains have been
 formed based on type/state_key and are denoted by colour and are labelled with
-- 
cgit 1.5.1