Skip to content

Upgrading locally owned rooms

What is a room upgrade? Should I upgrade my room?

In Matrix, every room has a "room version" - a set of rules that defines how it works at the protocol level. This allows new features and bug fixes to be applied to new rooms without breaking old ones.

Rooms don't track new room versions automatically. If you want the users in a room to benefit from the features and bug fixes in a newer room version, it is necessary to "upgrade" the room.

The Matrix way to handle this is to:

  • Create a new room with the desired settings, and then
  • Create a link between old and new room.

Element provides customers with client features and administrator tooling to streamline this process.

Advanced upgrading

The upgrade process is very flexible, and can be used for a variety of room maintenance purposes besides updating the room version, including downgrading room versions and changing otherwise immutable room properties. This usage is beyond the scope of this document.

Limitations of automation

The decentralised nature of Matrix means that some aspects of a room upgrade are conducted on a "best effort" basis. Synapse and Element will do their best to provide a smooth user experience, but there may be some circumstances that cannot be mitigated automatically. Following this guide will help to minimise disruption and to anticipate any speed bumps.

Performing a room upgrade

Note

We recommend to read this section in its entirety and make a plan before starting to upgrade rooms. Room upgrades can be disruptive for users. Getting it right on the first try will minimise friction for your users.

Before you start

At a high level we recommend running:

  • A single room upgrade as a Room Administrator for business-as-usual room upgrades to take advantage of new, optional features, and
  • A bulk room upgrade as a Server Administrator when it is necessary to upgrade many rooms simultaneously, such as when deploying a security fix.

Choose the tooling that best solves your immediate need.

Running a single room upgrade as a Room Administrator

A Room Administrator can use the Element Web client to perform a single room upgrade by sending a /upgraderoom command in room.

We recommend this approach for business-as-usual room upgrades to take advantage of new, optional features.

Prerequisites

When you upgrade a room as a room administrator, the user performing the upgrade needs the permission (aka power level) to send a m.room.tombstone event. This permission is called "Upgrade the room" in Element Web settings.

Recommendations

Communicate the upgrade plan to your users

Letting users know that the upgrade is taking place will help them to understand if something happens that they don't expect. In particular, warning them about known user experience limitations in advance will help them to manage the upgrade smoothly.

Known user experience limitations when performing a single room upgrade
  • If you upgrade a public room in this way, users in the old room will see the signpost event (the "tombstone" event) pointing them to the new room, but won't follow it automatically
  • If you upgrade a private room in this way, your account will invite the users from the old room to the new room. They will have to accept the invites themselves.
  • Widgets will not be copied from the old room to the new - any widgets will have to be reprovisioned manually.
  • Pinned messages will not be copied from the old room to the new - any pinned messages will have to be resent in the new room and pinned again.
Choose the right account

You should choose the "right" account on the "right" homeserver to perform your upgrade. The account that starts the upgrade decides which homeserver performs the upgrade. Here are some important factors to guide your choice:

  1. Users may have set up aliases - shareable addresses to find the room that are hosted by a specific homeserver. A homeserver can only update aliases that it hosts. Only aliases on the upgrading homeserver transfer automatically. However, you can (and should) always update the aliases on other homeservers after the upgrade, using respective accounts on these servers.
  2. Homeservers may publish a room directory. As with aliases, only the directory of the upgrading homeserver will update automatically, and updates on other servers will need to be handled manually.
  3. If you are using spaces to organise rooms, the user upgrading a room should have sufficient permissions in the parent space to update the reference from the old to the upgraded room. If the user does not have permission to edit the parent space, the space will continue to link to the old room.
  4. Room version 12 introduces some changes to room ownership semantics, such as irrevocable full control of the room. We recommend you use a long-lived service account, such as the admin bot, to upgrade your rooms. Using a separate service account to execute the upgrade means that this account will be the creator of the new room with the new special access rights.
Bots and integrations

Bots and integrations in your rooms may require additional manual migration steps. After upgrading, check your bots and integrations and if necessary reconfigure them for the new room.

Integrations with known upgrade compatibility issues

The following integrations are known not to work with room upgrades or with the latest room version (v12). If you are using these integrations please wait until a fix has been released:

  • HookShot
  • IRC, XMPP, and Slack bridges
Rate limits

The single room upgrade is best suited to upgrading one room at a time. Larger upgrades might be limited by server rate limits. Certain actions, such as creating a room, can only be performed a few times in sequence before needing to wait. If you have a lot of room to upgrade, please consider using the bulk room upgrade process described below.

Executing the single room upgrade as a Room Administrator

Having signed in as the most suitable account (see above):

  • Navigate to the room you want to upgrade

  • Type /roomupgrade 12 to upgrade to room version 12 (the latest version at time of writing this guide)

    in_composer_room_upgrade.png

  • Read the guidance in the pop-up, and click 'Upgrade' to execute the upgrade.

    upgrade_public_room.png

    upgrade_private_room.png

Running a bulk room upgrade as a Server Administrator

If the room contains a local room administrator, it can be upgraded by a Server Administrator using the Synapse Admin API /upgrade_local_rooms endpoint. This is usually used for upgrading rooms en masse, a process known as bulk room upgrade, though the API can also be used to upgrade a single room.

We recommend this approach when it is necessary to upgrade lots of rooms simultaneously, such as when deploying a security fix.

Prerequisites

You will need access to an account with Server Administrator privileges and to be running Synapse Pro to use the bulk room upgrade feature. This upgrade is initiated by making an HTTP request to the Synapse Admin API, so you'll need to be familiar with tooling required to execute such a request, such as a terminal and curl.

Please see our Synapse Admin API documentation for more details getting started here.

Recommendations

Communicate the upgrade plan to your users

Letting users know that the upgrade is taking place will help them to understand if something happens that they don't expect. In particular, warning them about known user experience limitations in advance will help them to manage the upgrade smoothly.

Known user experience limitations
  • All local users will join the upgraded rooms automatically
  • Users on remote servers will not join the upgraded room automatically:
    • For public rooms, remote users will see the signpost event (the "tombstone" event) pointing to the new room, but won't follow it automatically
    • For private rooms, users will receive an invite to the new room, but will have to accept it manually
  • Widgets will not be copied from the old room to the new - any widgets will have to be reprovisioned manually.
  • Pinned messages will not be copied from the old room to the new - any pinned messages will have to be resent in the new room and pinned again.
Which user upgrades the room?

You will initiate the upgrade by making a call to the Synapse Admin API as a Server Administrator. The bulk room upgrade tool will then execute the upgrade by choosing the most suitable member of the room and "puppeting" them - using their account to execute the room upgrade.

The tool will try and use the room's creator to execute the upgrade. If this is not possible, it will fall back to the local user with the highest power level. If no local user with sufficient power is a member of the room, the upgrade will not be executed for that room.

Bots and integrations

Bots and integrations in your rooms may require additional manual migration steps. After upgrading, check your bots and integrations and if necessary reconfigure them for the new room.

Integrations with known upgrade compatibility issues

The following integrations are known not to work with room upgrades or with the latest room version (v12). If you are using these integrations please wait until a fix has been released:

  • Element's audit and admin functionality relies on Admin bot and Audit bot which are currently incompatible with room upgrades and will not work with room v12.
  • HookShot
  • IRC and XMPP bridges

Executing the bulk room upgrade as a Server Administrator

Upgrading all local rooms

This is the main API and it upgrades all local rooms, optionally filtered to those matching the request parameters.

By default "DM rooms" will not be upgraded.

Note

This request may take a long time to complete, and potentially time out. The upgrade process will continue running and subsequent calls (with the same parameters) will be deduplicated and return the same response as the original request.

If a second request is sent with different parameters, it will fail if an upgrade is still in progress.

To cancel an update, restart the server.

This is a POST request with URL /_synapse/io.element/admin/v1/upgrade_local_rooms and a JSON body:

Key Required? Default Description
room_version Yes The target room version to upgrade the rooms to
upgrade_dm_rooms No False Whether to upgrade DM rooms, i.e. private rooms with two users.
only_public_rooms No False If set to true, only public rooms will be upgraded (i.e. those with join_rules set to public).
only_with_federated_users No False If set to true, only rooms that have (or have had) federated users in them will be upgraded. This is useful to avoid upgrading rooms that are only used by local users and are not federated.

Example request:

POST /_synapse/io.element/admin/v1/upgrade_local_rooms
{
    "room_version": "12",
    "only_public_rooms": false,
    "only_with_federated_users": false
}

Example response:

200 OK
{
    "success": true,
    "failed": 0,
    "upgraded": 100,
}

Tip

To send the above request as curl command:

curl --header "Authorization: Bearer <token>" \
"http://127.0.0.1:8008/_synapse/io.element/admin/v1/upgrade_local_rooms" \
-X POST \
-d '{"room_version": "12","only_public_rooms": false,"only_with_federated_users": false}'
Upgrading a specific room

This API upgrades a specific room in the same manner as the API above. This is primarily intended to allow server admins to test the UX of room upgrades before upgrading all rooms.

This is a POST request with URL /_synapse/io.element/admin/v1/upgrade_local_room?room_id=<room_id> and a JSON body:

Key Required? Default Description
room_version Yes The target room version to upgrade the rooms to

Example request:

POST /_synapse/io.element/admin/v1/upgrade_local_room?room_id=!foo:example.com
{
    "room_version": "12",
}

Example response:

200 OK
{
    "success": true,
}

Tip

To send the above request as curl command:

curl --header "Authorization: Bearer <token>" \
"http://127.0.0.1:8008/_synapse/io.element/admin/v1/upgrade_local_room?room_id=!foo:example.com" \
-X POST \
-d '{"room_version": "12","only_public_rooms": false,"only_with_federated_users": false}'