This commit is contained in:
qubedmaiska 2025-04-16 10:37:02 -04:00
commit cf30f8bab8
No known key found for this signature in database
GPG key ID: 204BCE0FD52C0501
15 changed files with 363 additions and 229 deletions

View file

@ -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 [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
@ -62,60 +66,35 @@ on any GNU/Linux system.
[user@restore ~]$ sudo dnf install rpmdevtools
5. Extract the `scrypt` binary from the RPM.
5. Extract the `scrypt` binary from the RPM and make it conveniently
available.
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
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. Untar the backup metadata from the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
backup-header backup-header.hmac qubes.xml.000.enc
backup-header
backup-header.hmac
qubes.xml.000.enc
vm1/private.img.000.enc
vm1/private.img.001.enc
vm1/private.img.002.enc
vm1/icon.png.000.enc
vm1/firewall.xml.000.enc
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.
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`.
Type in your passphrase (it will be visible on screen!) and press Enter.
3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
encrypted *and integrity protected* version of `backup-header`).
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
@ -123,34 +102,34 @@ 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`:
4. 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=20230405T123455-1234
5. Set `backup_id` to the value in the last line of `backup-header`:
5. 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
[user@restore ~]$ backup_id=20230405T123455-1234
6. Verify the integrity of your data, decrypt, decompress, and extract
`private.img`:
6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm1/private.img
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
qubes.xml
- If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
@ -158,23 +137,66 @@ 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.
if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
-d` in the command above. You might need to install a package of the same
name (in this example, `bzip2`) through your distribution's package manager.
7. Mount `private.img` and access your data.
7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
whose data you wish to restore. If you install the `xmlstarlet` package, the
following command will convert `qubes.xml` to a friendlier listing for this
purpose:
[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!
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
-n qubes.xml
anon-whonix
debian-11
default-mgmt-dvm
disp2345
fedora-37
fedora-37-dvm
personal vm123/
sys-firewall
sys-net
sys-usb
sys-whonix
untrusted
vault vm321/
whonix-gw-16
whonix-ws-16
whonix-ws-16-dvm
work
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.
The example output above shows that the backup file includes a qube named
`personal` and a qube named `vault`, with `backup-path` values of `vm123/`
and `vm321/` respectively. (Every other listed qube was not selected to be
included in the backup file.) Use the corresponding value to untar the
necessary data files of the qube:
- **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:
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
https://github.com/QubesOS/qubes-doc.git
8. Verify and decrypt the backed up data, decompress it, and extract it.
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm123/private.img
If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
Also see the note in step 6 about substituting a different compression
program for `gzip`.
9. Mount `private.img` and access your data.
[user@restore ~]$ sudo mkdir /mnt/img
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
[user@restore ~]$ ls /mnt/img/home/user/
example_data_file.txt
...
Success! If you wish to recover data from more than one qube in your backup,
simply repeat steps 7, 8, and 9 for each additional qube.

View file

@ -89,7 +89,7 @@ the other. Alice's setup looks like this:
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
she doesn't want to get bogged down doing with all that and figures it
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
OS doesn't judge her this and just gives her the freedom to do things however
OS doesn't judge her for this and just gives her the freedom to do things however
she likes while keeping everything securely compartmentalized. At times like
these, she takes comfort in knowing that things can be messy and disorganized
*within* a qube while her overall digital life remains well-organized.