From 61966e12f2219edb6b18dd9642fbed71faf511b2 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Thu, 13 Mar 2025 17:35:07 +0000 Subject: [PATCH] syn2mas: document new tool --- docs/setup/migration.md | 101 +++++++++++++++++++++++++++++----------- 1 file changed, 74 insertions(+), 27 deletions(-) diff --git a/docs/setup/migration.md b/docs/setup/migration.md index 19ac21288..c33a1e5e0 100644 --- a/docs/setup/migration.md +++ b/docs/setup/migration.md @@ -18,28 +18,29 @@ There will be tools to help with the migration process itself. But these aren't 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` +### Is your setup ready to be migrated? -The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@vector-im/syn2mas): +#### SAML2 and LDAP Single Sign-On Providers are not supported -```sh -npm install -g @vector-im/syn2mas -``` +A deployment which requires SAML or LDAP-based authentication should use a service like [Dex](https://github.com/dexidp/dex) to bridge between the SAML provider and the authentication service. +MAS is different from Synapse in that it does **not** have built-in support for SAML or LDAP-based providers. -### Run the migration advisor +#### Custom password providers are not supported -You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver. +If your Synapse homeserver currently uses a custom password provider module, please note that MAS does not support these. -```sh -syn2mas --command=advisor --synapseConfigFile=homeserver.yaml -``` +#### SQLite databases are not supported -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. +It is worth noting that MAS currently only supports PostgreSQL as a database backend. ### Install and configure MAS alongside your existing homeserver Follow the instructions in the [installation guide](installation.md) to install MAS alongside your existing homeserver. +You'll need a blank PostgreSQL database for MAS to use; it does not share the database with the homeserver. + +Set up a configuration file but don't start MAS, or create any users, yet. + #### Local passwords Synapse uses bcrypt as its password hashing scheme while MAS defaults to using the newer argon2id. @@ -51,63 +52,109 @@ Example passwords configuration: passwords: enabled: true schemes: - - version: 1 + - version: 1 # TODO I think v:2 has to come first in this list algorithm: bcrypt - version: 2 algorithm: argon2id ``` +If you have a pepper configured in your Synapse password configuration, you'll need to match that on version 1 of the equivalent MAS configuration. + +The migration checker will inform you if this has not been configured properly. + ### 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. +If you are using an upstream SSO provider, then you will need to configure the upstream provider in MAS manually. -Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool. +MAS does not support SAML or LDAP upstream providers. +If you are using one of these, you will need to use an adapter such as Dex at this time, +but we have not yet documented this procedure. -### Prepare the MAS database +Each upstream provider that was used by at least one user in Synapse will need to be configured in MAS. -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: +Set the `synapse_idp_id` attribute on the provider to: -```sh -mas-cli config sync -``` +- `"oidc"` if you used an OIDC provider in Synapse's legacy `oidc_config` configuration section. +- `"oidc-myprovider"` if you used an OIDC provider in Synapse's `oidc_providers` configuration list, + with a `provider` of `"myprovider"`. + (This is because Synapse prefixes the provider ID with `oidc-` internally.) -### Do a dry-run of the import to test +Without the `synapse_idp_id`s being set, syn2mas does not understand which providers +in Synapse correspond to which provider in MAS. + +!!!!!!!!! TODO add an example here + +The migration checker will inform you if a provider is missing from MAS' config. + +### Run the migration checker + +You can use the `check` command of the `syn2mas` tool to identify configuration problems before starting the migration. +You do not need to stop Synapse to run this command. ```sh -syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun +mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml check ``` -If no errors are reported then you can proceed to the next step. +This will either output a list of errors and warnings, or tell you that the check completed with no errors or warnings. + +If you have any errors, you must resolve these before starting the migration. + +If you have any warnings, please read, understand and possibly resolve them. +With that said, resolving them is not strictly required before starting the migration. + +### Do a dry-run of the import to test + +!!!!!!! TODO we don't have an exact dry-run mode exposed at the moment... ## 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 +### Backup your data and configuration As with any migration, it is important to backup your data before proceeding. +We also suggest making a backup copy of your homeserver's known good configuration, +before making any changes to enable MAS integration. + ### Shutdown the homeserver This is to ensure that no new sessions are created whilst the migration is in progress. -### Configure the homeserver +### Configure the homeserver to enable MAS integration Follow the instructions in the [homeserver configuration guide](homeserver.md) to configure the homeserver to use MAS. ### Do the import -Run `syn2mas` in non-dry-run mode. +Once the homeserver has been stopped, MAS has been configured (but is not running!) +and you have a successful migration check, +run `syn2mas`'s `migrate` command. + +Other than the change of command word, the syntax is exactly the same as the `check` command. ```sh -syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false +mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml migrate ``` +#### What to do if it goes wrong + +If the migration fails with an error: + +- You can either try to fix the error and make another attempt by re-running the command; or +- you can revert your homeserver configuration (so MAS integration is disabled once more) + and abort the migration for now. In this case, you should not start MAS up. + +Please report migration failures to the developers. + ### Start up the homeserver Start up the homeserver again with the new configuration. +### Start up MAS + +Start up MAS. + ### Update or serve the .well-known The `.well-known/matrix/client` needs to be served as described [here](./well-known.md).