Configuration Reference - Experiments

Some features in Hammerhead 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 Hammerhead supports, and their related configuration options.

Note

As these proposals are unstable, they may drastically change over their lifetime, which means Hammerhead’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 Hammerhead 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 Hammerhead with the non-default federation build tag in addition to enabling this experiment: HAMMERHEAD_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.

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.