Update and improve Emergency backup restore v4 page

[andrewdavidwong]

Summary of changes:

• Update formatting and style to be consistent with the rest of the docs
• Improve language
• Clarify instructions
• Improve organization

One significant change is the removal of the portion that began with "to extract only specific VMs." There were several problems with this:

1. It was too easy to accidentally follow this part, only to realize in the following step that it wasn't necessary. "To extract only specific VMs" is not clear. Most readers probably won't realize that's something they don't want to do, because it sounds like something they do want to do.
2. It's not clear why this portion is even needed, because following the normal instructions actually only extracts a single VM at a time anyway! So this portion seems redundant.
3. More importantly, these mini-instructions bypass the integrity checking step, which is a major security risk. We should not be telling users to do that.
4. The instructions themselves are confusing and difficult to follow. Even if you try to follow them to the letter, you just end up with a private.img.000.enc file, and then you don't know what to do after that. If you try to pick up with next step, it makes no sense.
5. The very next step has you save your backup passphrase with read -r, whereas these instructions have you enter it directly. That makes no sense. At the very least, the instructions should be reorganized to be sensible.

I also changed the portion on aliasing binaries because the existing command didn't work for me on Debian 11 minimal ("command not found"). Adding a space after the asterisk caused a scrypt error, where it didn't recognize that I was using dec even though I was.

[rustybird]

2. It's not clear why this portion is even needed, because following the normal instructions actually only extracts a single VM at a time anyway! So this portion seems redundant.

There are two phases: The first one extracts encrypted data from the backup file, the second one decrypts and reassembles it. The deleted portion of the instructions is about limiting the amount of data that has to be extracted in the first phase. E.g. if you have a 100 GB backup file containing 5 VMs weighing in at 20 GB each and want to restore one VM, you should only need 20 + 20 GB free space in the rescue environment (and spend less time) instead of 100 + 20 GB.

[andrewdavidwong]

There are two phases: The first one extracts encrypted data from the backup file, the second one decrypts and reassembles it. The deleted portion of the instructions is about limiting the amount of data that has to be extracted in the first phase. E.g. if you have a 100 GB backup file containing 5 VMs weighing in at 20 GB each and want to restore one VM, you should only need 20 + 20 GB free space in the rescue environment (and spend less time) instead of 100 + 20 GB.

Thank you for this information! That makes sense, but for all the other reasons I listed, it still doesn't seem worthwhile to retain this portion in the documentation in its current form. I'd be open to including it in some other way (e.g., in a separate section at the end) if you have suggestions.

[rustybird]

it still doesn't seem worthwhile to retain this portion in the documentation in its current form.

Oh yeah it was a big mess. On rereading it though, part of the problem with this portion is that despite sounding like it's an alternative approach, it included steps that really have to be done in every case:

Now that you have the decrypted qubes.xml.000 [should actually refer to qubes.xml] file, search for the backup-path property inside of it. With the backup-path, extract only the files necessary for your VM (vmX).

Otherwise how would the user even know which anonymized vm123/ directory corresponds to their VM named foo...

One way to untangle this is would be to change the "Untar the main backup file" step to extract only the backup metadata backup-header backup-header.hmac qubes.xml.000.enc, then verify the integrity of backup-header, then decrypt qubes.xml and look up the VM directory. Then after that, we might as well extract only that specific VM directory (instead of everything), bringing the phase one instructions in line with the phase two instructions that also decrypt only a specific VM. I could submit this as a PR (to the emergency-backup-restore-v4 branch?) if you like.

[andrewdavidwong]

I could submit this as a PR (to the emergency-backup-restore-v4 branch?) if you like.

That would be great! Thank you!

[rustybird]

https://github.com/QubesOS/qubes-doc/pull/1302