Migrating an existing homeserver

One of the design goals of MAS has been to allow it to be used to migrate an existing homeserver to an OIDC-based architecture.

Specifically without requiring users to re-authenticate and that non-OIDC clients continue to work.

Features that are provided to support this include:

  • Ability to import existing password hashes from Synapse
  • Ability to import existing sessions and devices
  • Ability to import existing access tokens linked to devices (ie not including short-lived admin puppeted access tokens)
  • Ability to import existing upstream IdP subject ID mappings
  • Provides a compatibility layer for legacy Matrix authentication

There will be tools to help with the migration process itself. But these aren't quite ready yet.

Preparing for the migration

The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.

Get syn2mas

The easiest way to get syn2mas is through npm:

npm install -g @vector-im/syn2mas

Run the migration advisor

You can use the advisor mode of the syn2mas tool to identify extra configuration steps or issues with the configuration of the homeserver.

syn2mas --command=advisor --synapseConfigFile=homeserver.yaml

This will output WARN entries for any identified actions and ERROR entries in the case of any issues that will prevent the migration from working.

Install and configure MAS alongside your existing homeserver

Follow the instructions in the installation guide to install MAS alongside your existing homeserver.

Map any upstream SSO providers

If you are using an upstream SSO provider then you will need to provision the upstream provide in MAS manually.

Each upstream provider will need to be given as an --upstreamProviderMapping command line option to the import tool.

Prepare the MAS database

Once the database is created, it still needs to have its schema created and synced with the configuration. This can be done with the following command:

mas-cli config sync

Do a dry-run of the import to test

syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun

If no errors are reported then you can proceed to the next step.

Doing the migration

Having done the preparation, you can now proceed with the actual migration. Note that this will require downtime for the homeserver and is not easily reversible.

Backup your data

As with any migration, it is important to backup your data before proceeding.

Shutdown the homeserver

This is to ensure that no new sessions are created whilst the migration is in progress.

Configure the homeserver

Follow the instructions in the homeserver configuration guide to configure the homeserver to use MAS.

Do the import

Run syn2mas in non-dry-run mode.

syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false

Start up the homeserver

Start up the homeserver again with the new configuration.

Update or serve the .well-known

The .well-known/matrix/client needs to be served as described here.