Configuration Reference - Experiments

Some features in Venator are gated behind “experiments”, sometimes referred to as “labs”, “feature flags”, “unstable flags”, and other related terminologies. These configurations control potentially experimental changes to behaviours in the server, imposed by Matrix Spec Proposals (MSCs).

In order to provide a more consistent experience, all experiments are disabled by default, and must be explicitly enabled in the configuration. However, when generating a new configuration file, some experiments may be enabled or pre-configured by default, but only when they are deemed to be relatively stable (i.e. won’t change much between now and their merge time), and provide an unquestionable benefit to the daily UX.

This document will detail every experimental proposal that Venator supports, and their related configuration options.

Note

As these proposals are unstable, they may drastically change over their lifetime, which means Venator’s implementation may fall out of sync, potentially even to an incompatible degree.

When an MSC is merged into the spec, the experimental option will be removed from the configuration. This will not raise any alarms during init, but you should keep an eye on release notes to know if you need to change any new configuration options.

Federation

Federation allows your homeserver to communicate with other homeservers, and vice versa. In its smallest form, it can be used for (for example) server1.localhost:8008 to communicate with server2.localhost:8008, or in the greater scheme, talk to any server on the public Matrix federation network.

Warning

Federation is not itself a spec proposal, but is a complex component of Venator that is still under rapid development, and may be broken in unique and wonderful ways. Please do not enable this if you do not know what you are doing, or are not aware of the potential consequences of doing so.

You must compile Venator with the non-default federation build tag in addition to enabling this experiment: VENATOR_BUILD_TAGS=federation ./build.sh. See compiling for more information on the build script.

• enabled (boolean): When true, federation is bi-directionally enabled.
• acl (mapping, optional): A server ACL event content that can be used to denylist or allowlist federation traffic. In addition to the standard content, there is also the hide_blocks boolean option, which when enabled, will return HTTP 500 to denied origins, instead of a 403. The default is to allow all servers.

Example:

experiments:
  federation:
    enabled: true
    acl:
      hide_blocks: true
      allow: ['*']
      deny:
        - badserver1.example
        - '*.bad.domain'

If you wanted to allowlist traffic, you would do such like so:

experiments:
  federation:
    enabled: true
    acl:
      allow: ['server1', 'server2']
      # do not deny: *, as deny overrules allow.

MSC4127

MSC4127: Removal of query string auth removes authentication via the query string parameter access_token, instead requiring clients to authenticate via the Authorization header. This may break some very old scripts, but the programs that would be broken by this change likely don’t work with Venator anyway.

Example:

experiments:
  msc4127:
    enabled: true

MSC4342

MSC4342: Limiting the number of devices per user ID limits the number of sessions (devices) to 30 per user. When a user has 30 devices, they will either be unable to log in and create new devices, or their oldest device will be deleted upon login to make “room” for the new device. They will always be able to resume existing devices.

By limiting the number of devices per user, the load on the server will be reduced, end-to-end encryption will become faster and more reliable, and it slightly increases the security of an account by reducing the number of sessions that may become compromised.

Warning

Automatically logging out old devices (auto_reclaim: true) may cause minor data loss for the user. Devices accumulate encryption keys, and if they are not connected to the server-side key backup, will lose them when deleted. This means that the user may lose some encryption keys, leading to “unable to decrypt” errors.

On the other hand, in the unlikely event that the user has lost access to all of their sessions, they will not be able to log out. In this case, they will either have to contact a server admin out-of-band for assistance, or reset their password, logging out all devices in the process. The same warning w.r.t. data loss as above applies, in this case.

• enabled (boolean): When true, enables this experiment’s behaviour. Can be safely turned off later.
• auto_reclaim (boolean): When true, the user’s oldest device will be logged out when they log in with a new one. Otherwise, their login attempt will be refused, until they manually log out elsewhere.

Example:

experiments:
  msc4342:
    enabled: true
    auto_reclaim: true

MSC4383

MSC4383: Client-Server Discovery of Server Version extends the response of GET /_matrix/client/versions to additionally return some server version metadata, including the name of the server (in this case, Venator), and the short version string. This may improve diagnostic feedback generated by clients.

Example:

experiments:
  msc4383:
    enabled: true

MSC4420

MSC4420: Duplicate one-time key error response for /keys/upload modifies the handling of POST /_matrix/client/v3/keys/upload to explicitly return an error response if a client tries to re-upload an existing one-time key. If this experiment is disabled, duplicate one-time keys are simply ignored.

Example:

experiments:
  msc4420:
    enabled: true

MSC4437

MSC4437: Endpoint to replace entire profile adds the PUT HTTP method to /_matrix/client/v3/profile/{userId}, which allows clients to replace the invoking user’s entire profile at once, rather than having to atomically PUT and DELETE individual fields. In effect, a bulk update.

Note that until the proposal is accepted, the route will be PUT /_matrix/client/unstable/com.beeper.msc4437/profile/{userId}, per the proposal’s unstable prefix.

• enabled (boolean): When true, the PUT HTTP method will allow users to replace their entire profile.

Example:

experiments:
  msc4437:
    enabled: true