From 2c5601ccf1c85f6de72cd98591bb470ce9fc847e Mon Sep 17 00:00:00 2001 From: Millesimus <32270710+Millesimus@users.noreply.github.com> Date: Tue, 9 Aug 2022 17:29:01 +0200 Subject: [PATCH] add migration tutorial * Create migrating_to_new_device.md * Add link to Readme for further information. * Added some info * Make separate backup guide and integrate Readme information with new guides. Co-authored-by: Licaon_Kter --- README.md | 12 ++------ docs/user/backup.md | 19 +++++++++++++ docs/user/migrating_to_new_device.md | 42 ++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 9 deletions(-) create mode 100644 docs/user/backup.md create mode 100644 docs/user/migrating_to_new_device.md diff --git a/README.md b/README.md index 689af33d5..6e7833282 100644 --- a/README.md +++ b/README.md @@ -273,16 +273,10 @@ the translation team and then step by our group chat on and introduce yourself to `iNPUTmice` so he can approve your join request. #### How do I backup / move Conversations to a new device? -On the one hand Conversations supports Message Archive Management to keep a server side history of your messages so when migrating to a new device that device can display your entire history. However that does not work if you enable OMEMO due to its forward secrecy. (Read [The State of Mobile XMPP in 2016](https://gultsch.de/xmpp_2016.html) especially the section on encryption.) -As of version 2.4.0 an integrated Backup & Restore function will help with this, go to Settings and you’ll find a setting called Create backup. A notification will pop-up during the creation process that will announce you when it's ready. After the files, one for each account, are created, you can move the **Conversations** folder *(if you want your old media files too)* or only the **Conversations/Backup** folder *(for OMEMO keys and history only)* to your new device (or to a storage place) where a freshly installed Conversations can restore each account. Don't forget to enable the accounts after a successfull restore. - -This backup method will include your OMEMO keys. Due to forward secrecy you will not be able to recover messages sent and received between creating the backup and restoring it. If you have a server side archive (MAM) those messages will be retrieved but displayed as *unable to decrypt*. For technical reasons you might also lose the first message you either sent or receive after the restore; for each conversation you have. This message will then also show up as *unable to decrypt*, but this will automatically recover itself as long as both participants are on Conversations 2.3.11+. Note that this doesn’t happen if you just transfer to a new phone and no messages have been exchanged between backup and restore. - -In the vast, vast majority of cases you won’t have to manually delete OMEMO keys or do anything like that. Conversations only introduced the official backup feature in 2.4.0 after making sure the *OMEMO self healing* mechanism introduced in 2.3.11 works fine. - -**WARNING**: Be sure to know your accounts passwords or find ways to reset them **before** doing the backup as the files are encrypted using those passwords and the Restore process will ask for them. -**WARNING**: Do not use the restore backup feature in an attempt to clone (run simultaneously) an installation. Restoring a backup is only meant for migrations or in case you’ve lost the original device. +See the dedicated guides for +- [backups](docs/user/backup.md) +- [migrations](docs/user/migrating_to_new_device.md) #### Conversations is missing a certain feature diff --git a/docs/user/backup.md b/docs/user/backup.md new file mode 100644 index 000000000..4d81d8ddd --- /dev/null +++ b/docs/user/backup.md @@ -0,0 +1,19 @@ +# Making a backup of Conversations + +This tutorial explains how you can backup your Conversations data. + +**WARNING**: Do not use the restore backup feature in an attempt to clone (run simultaneously) an installation. Restoring a backup is only meant for migrations or in case you’ve lost the original device. + +1. Make sure that you know the password to your account(s)! You will need it later to decrypt your backup. +2. Deactivate all your account(s): on the chat screen, tap on the three buttons in the upper right, and go to "manage accounts". +3. Go back to Settings, scroll down until you find the option to create a new backup. Tap on that option. +4. Wait, until the notification tells you that the backup is finished. +5. Move the backup to whatever location you feel save with. + +Done! + +## Further information / troubleshooting +### Unable to decrypt +This backup method will include your OMEMO keys. Due to forward secrecy you will not be able to recover messages sent and received between creating the backup and restoring it. If you have a server side archive (MAM) those messages will be retrieved but displayed as *unable to decrypt*. For technical reasons you might also lose the first message you either sent or receive after the restore; for each conversation you have. This message will then also show up as *unable to decrypt*, but this will automatically recover itself as long as both participants are on Conversations 2.3.11+. Note that this doesn’t happen if you just transfer to a new phone and no messages have been exchanged between backup and restore. + +In the vast, vast majority of cases you won’t have to manually delete OMEMO keys or do anything like that. Conversations only introduced the official backup feature in 2.4.0 after making sure the *OMEMO self healing* mechanism introduced in 2.3.11 works fine. diff --git a/docs/user/migrating_to_new_device.md b/docs/user/migrating_to_new_device.md new file mode 100644 index 000000000..401a15386 --- /dev/null +++ b/docs/user/migrating_to_new_device.md @@ -0,0 +1,42 @@ +# Migrating to a new device + +This tutorial explains how you can transfer your Conversations data from an old to a new device. It assumes that you do not have Conversations installed on your new device, yet. It basically consists of three steps: + +1. Make a backup (old device) +2. Move that backup to your new device +3. Import the backup (new device) + +**WARNING**: Do not use the restore backup feature in an attempt to clone (run simultaneously) an installation. Restoring a backup is only meant for migrations or in case you’ve lost the original device. + +## 1. Make a backup (old device) +1. Make sure that you know the password to your account(s)! You will need it later to decrypt your backup. +2. Deactivate all your account(s): on the chat screen, tap on the three buttons in the upper right, and go to "manage accounts". +3. Go back to Settings, scroll down until you find the option to create a new backup. Tap on that option. +4. Wait, until the notification tells you that the backup is finished. + +## 2. Move that backup to your new device +1. Locate the backup. You should find it in your Files, either in *Conversations/Backup* or in *Download/Conversations/Backup*. The file is named after your account (*e.g. kim@example.org*). If you have multiple accounts, you find one file for each. +2. Use your USB cable or bluetooth, your Nextcloud or other cloud storage or pretty much anything you want to copy the backup from the old device to the new device. +3. Remember the location you saved your backup to. For instance, you might want to save them to the *Download* folder. + +## 3. Import the backup (new device) +1. Install Conversations on your new device. +2. Open Conversations for the first time. +3. Tap on "Use other server" +4. Tap on the three dot menu in the upper right corner and tap on "Import backup" +5. If your backup files are not listed, tap on the cloud symbol in the upper right corner to choose the files from the where you saved them. +6. Enter your account password to decrypt the backup. +7. Remember to activate your account (head back to "manage accounts", see step 1.2). +8. Check if chats work. + +Once confirmed that the new device is running fine you can just uninstall the app from the old device. + +Note: The backup only contains your text chats and required encryption keys, all the files need to be transferred separately and put on the new device in the same locations. + +Done! + +## Further information / troubleshooting +### Unable to decrypt +This backup method will include your OMEMO keys. Due to forward secrecy you will not be able to recover messages sent and received between creating the backup and restoring it. If you have a server side archive (MAM) those messages will be retrieved but displayed as *unable to decrypt*. For technical reasons you might also lose the first message you either sent or receive after the restore; for each conversation you have. This message will then also show up as *unable to decrypt*, but this will automatically recover itself as long as both participants are on Conversations 2.3.11+. Note that this doesn’t happen if you just transfer to a new phone and no messages have been exchanged between backup and restore. + +In the vast, vast majority of cases you won’t have to manually delete OMEMO keys or do anything like that. Conversations only introduced the official backup feature in 2.4.0 after making sure the *OMEMO self healing* mechanism introduced in 2.3.11 works fine.