From 9eb7926ffe515a044d0f4ec31ca9eecb5c54bc09 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:34:08 -0800 Subject: [PATCH 1/5] Update and improve Emergency backup restore v4 page - Update formatting and style to be consistent with the rest of the docs - Improve language - Clarify instructions - Improve organization --- .../backup-emergency-restore-v4.md | 109 ++++++++---------- 1 file changed, 47 insertions(+), 62 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 19367a24..38df4b12 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -12,13 +12,17 @@ title: Emergency backup recovery (v4) This page describes how to perform an emergency restore of a backup created on Qubes R4.X (which uses backup format version 4). -The Qubes backup system has been designed with emergency disaster recovery in -mind. No special Qubes-specific tools are required to access data backed up by -Qubes. In the event a Qubes system is unavailable, you can access your data on -any GNU/Linux system with the following procedure. +The Qubes backup system is designed with emergency disaster recovery in mind. No +special Qubes-specific tools are required to access data backed up by Qubes. In +the event a Qubes system is unavailable, you can access your data on any +GNU/Linux system by following the instructions on this page. -Required `scrypt` Utility -------------------------- +**Important:** You may wish to store a copy of these instructions with your +Qubes backups. All Qubes documentation, including this page, is available in +plain text format in the the [qubes-doc](https://github.com/QubesOS/qubes-doc) +Git repository. + +## Required `scrypt` utility In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this @@ -34,8 +38,8 @@ easier scripting, which means you'll need to enter the passphrase for each file separately, instead of using `echo ... | scrypt`. Here are instructions for obtaining a compiled `scrypt` binary. This example -uses an RPM-based system (Fedora), but the same general procedure should work -on any GNU/Linux system. +uses an RPM-based system (Fedora), but the same general procedure should work on +any GNU/Linux system. 1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys). @@ -46,7 +50,7 @@ on any GNU/Linux system. [user@restore ~]$ dnf download scrypt - or, if that doesn't work: + Or, if that doesn't work: [user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm @@ -66,17 +70,19 @@ on any GNU/Linux system. [user@restore ~]$ rpmdev-extract scrypt-*.rpm - 6. (Optional) Create an alias for the new binary. - - [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt" - -Emergency Recovery Instructions -------------------------------- +## Emergency recovery instructions **Note:** In the following example, the backup file is both *encrypted* and *compressed*. - 1. Untar the main backup file. + 1. (Optional) If you're working with binaries that you saved with your backup, + such as `scrypt` or `bzip2`, you can make things easier by aliasing those + binaries now, e.g., + + [user@restore ~]$ alias scrypt="/home/user/scrypt-*" + [user@restore ~]$ alias bzip2="/home/user/bzip2-*" + + 2. Untar the main backup file. [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 backup-header @@ -90,32 +96,15 @@ Emergency Recovery Instructions vm1/whitelisted-appmenus.list.000.enc dom0-home/dom0user.000.enc - **To extract only specific VMs:** Each VM in the backup file has its path - listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is - `password`.) - - [user@restore ~]$ cat backup-header | grep backup-id - backup-id=20190128T123456-1234 - [user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000 - Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password - [user@restore ~]$ tar -i -xvf qubes.xml.000 - - Now that you have the decrypted `qubes.xml.000` file, search for the - `backup-path` property inside of it. With the `backup-path`, extract only - the files necessary for your VM (`vmX`). - - [user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \ - backup-header backup-header.hmac vmX/ - - 2. Set the backup passphrase environment variable. While this isn't strictly - required, it will be handy later and will avoid saving the passphrase in - the shell's history. + 3. Set the backup passphrase environment variable. While this isn't strictly + required, it will be handy later and will avoid saving the passphrase in the + shell's history. [user@restore ~]$ read -r backup_pass - 3. Verify the integrity of `backup-header`. For compatibility reasons, - `backup-header.hmac` is an encrypted *and integrity protected* - version of `backup-header`. + 4. Verify the integrity of `backup-header`. For compatibility reasons, + `backup-header.hmac` is an encrypted *and integrity protected* version of + `backup-header`. [user@restore ~]$ set +H [user@restore ~]$ echo "backup-header!$backup_pass" |\ @@ -123,28 +112,31 @@ Emergency Recovery Instructions diff -qs backup-header backup-header.verified Files backup-header and backup-header.verified are identical - **Note:** If this command fails, it may be that the backup was tampered - with or is in a different format. In the latter case, look inside - `backup-header` at the `version` field. If it contains a value other than - `version=4`, go to the instructions for that format version: + **Note:** If this command fails, it may be that the backup was tampered with + or is in a different format. In the latter case, look inside `backup-header` + at the `version` field. If it contains a value other than `version=4`, go to + the instructions for that format version: - [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/) - [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/) - 4. Read `backup-header`: + 5. Read `backup-header`. [user@restore ~]$ cat backup-header version=4 encrypted=True compressed=True compression-filter=gzip - backup_id=20161020T123455-1234 + hmac-algorithm=scrypt + backup-id=20161020T123455-1234 - 5. Set `backup_id` to the value in the last line of `backup-header`: + 6. Set `backup_id` to the value in the last line of `backup-header`. (Note that + there is a hyphen in `backup-id` in the file, whereas there is an underscore + in `backup_id` in the variable you're setting.) [user@restore ~]$ backup_id=20161020T123455-1234 - 6. Verify the integrity of your data, decrypt, decompress, and extract - `private.img`: + 7. Choose a qube whose data you wish to restore. Verify the data's integrity, + decrypt it, decompress it, and extract it. [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \ f_dec=${f_enc%.enc}; \ @@ -157,24 +149,17 @@ Emergency Recovery Instructions **Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program in the command above. - This information is contained in `backup-header` (see step 4). For example, - if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the - command above. + This information is contained in `backup-header` (see step 5). For example, + if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip + -d` in the command above. - 7. Mount `private.img` and access your data. + 8. Enter the decrypted directory, mount `private.img`, and access your data. + [user@restore ~]$ cd vm1/ [user@restore vm1]$ sudo mkdir /mnt/img [user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/ [user@restore vm1]$ cat /mnt/img/home/user/your_data.txt This data has been successfully recovered! - 8. Success! If you wish to recover data from more than one VM in your backup, - simply repeat steps 6 and 7 for each additional VM. - - **Note:** You may wish to store a copy of these instructions with your - Qubes backups in the event that you fail to recall the above procedure - while this web page is inaccessible. All Qubes documentation, including - this page, is available in plain text format in the following Git - repository: - - https://github.com/QubesOS/qubes-doc.git +Success! If you wish to recover data from more than one qube in your backup, +simply repeat steps 7 and 8 for each additional qube. From b6c99d486bf7fb38f9958dabb56107cf20223e7d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:53:29 -0800 Subject: [PATCH 2/5] Fix typo --- user/how-to-guides/backup-emergency-restore-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 38df4b12..026de11f 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -19,8 +19,8 @@ GNU/Linux system by following the instructions on this page. **Important:** You may wish to store a copy of these instructions with your Qubes backups. All Qubes documentation, including this page, is available in -plain text format in the the [qubes-doc](https://github.com/QubesOS/qubes-doc) -Git repository. +plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git +repository. ## Required `scrypt` utility From 39342e8c98066603839d7f77ce0416e4af439b75 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 23 Nov 2022 17:55:04 -0800 Subject: [PATCH 3/5] Clarify example --- user/how-to-guides/backup-emergency-restore-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 026de11f..1caa526b 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -135,8 +135,8 @@ any GNU/Linux system. [user@restore ~]$ backup_id=20161020T123455-1234 - 7. Choose a qube whose data you wish to restore. Verify the data's integrity, - decrypt it, decompress it, and extract it. + 7. Choose a qube whose data you wish to restore (in this example, `vm1`). + Verify the data's integrity, decrypt it, decompress it, and extract it. [user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \ f_dec=${f_enc%.enc}; \ From edbfa3c9b6fc133af765687e796520118cd7f3dc Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 11 Apr 2023 16:35:19 -0700 Subject: [PATCH 4/5] Update user/how-to-guides/backup-emergency-restore-v4.md Co-authored-by: Rusty Bird --- user/how-to-guides/backup-emergency-restore-v4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 1caa526b..ce04ba70 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -79,7 +79,7 @@ any GNU/Linux system. such as `scrypt` or `bzip2`, you can make things easier by aliasing those binaries now, e.g., - [user@restore ~]$ alias scrypt="/home/user/scrypt-*" + [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt" [user@restore ~]$ alias bzip2="/home/user/bzip2-*" 2. Untar the main backup file. From f43e54f3a5736f9ce972e0d4889dd42cc0dfff4d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 11 Apr 2023 16:42:34 -0700 Subject: [PATCH 5/5] Remove unnecessary example and step Per @rustybird's suggestions on #1279 --- user/how-to-guides/backup-emergency-restore-v4.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index ce04ba70..f3ca1129 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -76,11 +76,10 @@ any GNU/Linux system. *compressed*. 1. (Optional) If you're working with binaries that you saved with your backup, - such as `scrypt` or `bzip2`, you can make things easier by aliasing those - binaries now, e.g., + such as `scrypt`, you can make things easier by aliasing those binaries now, + e.g., [user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt" - [user@restore ~]$ alias bzip2="/home/user/bzip2-*" 2. Untar the main backup file. @@ -155,10 +154,9 @@ any GNU/Linux system. 8. Enter the decrypted directory, mount `private.img`, and access your data. - [user@restore ~]$ cd vm1/ - [user@restore vm1]$ sudo mkdir /mnt/img - [user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/ - [user@restore vm1]$ cat /mnt/img/home/user/your_data.txt + [user@restore]$ sudo mkdir /mnt/img + [user@restore]$ sudo mount -o loop vm1/private.img /mnt/img/ + [user@restore]$ cat /mnt/img/home/user/your_data.txt This data has been successfully recovered! Success! If you wish to recover data from more than one qube in your backup,