From bf537f31a26db997a71636647465e41400856487 Mon Sep 17 00:00:00 2001 From: ro Date: Thu, 20 May 2021 19:56:34 -0400 Subject: [PATCH 1/2] Add preliminary backup and restore instructions --- docs/admin/backup.rst | 177 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- 2 files changed, 178 insertions(+), 1 deletion(-) create mode 100644 docs/admin/backup.rst diff --git a/docs/admin/backup.rst b/docs/admin/backup.rst new file mode 100644 index 0000000..d91c1cd --- /dev/null +++ b/docs/admin/backup.rst @@ -0,0 +1,177 @@ +Backup and Restore +================== + +.. include:: ../includes/top-warning.rst + +QubesOS has a `backup utility `_ +that allows for backup and restoration of user-specified VMs. + +To perform backups, you will need: + + - an encrypted storage medium + - a secure place to store backup credentials + +Backup +------ + +Prepare files in ``dom0`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Files outside the ``dom0`` home folder aren't normally backed up by the +Qubes backup tool. Preserve key configuration files by coping them to the +home directory. + +In a ``dom0`` Terminal via **Q ▸ Terminal Emulator**: + + .. code-block:: sh + + mkdir ~/backup/ + cp -r /usr/share/securedrop-workstation-dom0-config/ ~/backup/ + +If you have customized :doc:`clipboard access ` +to SecureDrop Workstation, or have made any other customizations +involving RPC policies, back up related configuration files: + + .. code-block:: sh + + mkdir -p ~/backup/etc/qubes + mkdir ~/backup/etc/qubes-rpc + cp -a /etc/qubes/* ~/backup/etc/qubes/ + cp -a /etc/qubes-rpc/* ~/backup/etc/qubes-rpc + +Back up SecureDrop Workstation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ensure your storage medium is plugged in, attached to a VM, and mounted. +(LUKS-encrypted storage media may be attached to ``sd-usb``, or you may use a custom +VM of your choosing, if you are relying on another form of encryption such as +Veracrypt). + +Navigate to **Q ▸ System Tools ▸ Backup Qubes**, and move all VMs from +"Selected" to "Available" by pressing the ``<<`` button. + +To target a VM for backup, highlight it and move it into the "Selected" +column by pressing the ``>`` button. Select the following VMs: + + - ``dom0`` + - ``vault`` + - any customized VMs that you wish to preserve. + +You do not need to back up the ``sd-`` VMs. + +Click "Next", and in "Backup destination," specify the VM and directory +corresponding to your storage medium's current mount point. + +Set a strong, unique backup passphrase (7-word diceware), and ensure this +passphrase is stored securely outside SecureDrop Workstation. + +.. note:: + This passphrase protects sensitive + components of your SecureDrop instance, including the *Submission Private Key*. + Ensure that it is a very strong password and is stored securely. + +Uncheck "save backup profile," then proceed with the backup. + +QubesOS recommends verifying the integrity of the backup once the backup +completes. This can be done by using the Restore Backup GUI tool and selecting +"Verify backup integrity, but do not restore the data." For details, see the +`QubesOS backup documentation `_. + +Restore +------- + +Reinstall QubesOS +~~~~~~~~~~~~~~~~~ + +To restore SecureDrop Workstation, follow our +:doc:`pre-install tasks ` to provision a QubesOS system complete with +updated base templates. + +.. note:: + If you backed up a number of custom VMs, during the installer, you may opt + to un-select "create default application qubes (personal, work, untrusted, vault)". + +Manage Unused VMs +~~~~~~~~~~~~~~~~~ + +If you installed all default application VMs, remove the ``vault`` VM, since we +will replace it with the version in our backup. + + .. code-block:: sh + + qvm-prefs --set vault installed_by_rpm False + qvm-remove vault + +Restore Backup +~~~~~~~~~~~~~~ + +Plug in your backup medium and unlock it as during the backup. By default +on a new system, your peripheral devices will be managed by ``sys-usb``. +(For non-LUKS-based encryption media, you will need to install and configure the +appropriate software, either in ``sys-usb`` or in another VM). + +Navigate to **Q ▸ System Tools ▸ Restore Backup**, and enter the +location of the backup file. You do not need to adjust the default Restore +options, unless you have made customizations to the backup. Enter the +decryption/verification passphrase, and proceed to restore the backup. + +Your ``vault`` VM will be restored. + +The contents of the previous ``dom0`` will be backed up to a folder in the +new ``dom0`` home directory called ``home-restore-/dom0-home/user``. +In this guide we will refer to that location as ``$DOM0_BACKUP``. + +Open a terminal via **Q ▸ Terminal Emulator**: + + .. code-block:: sh + + cd $DOM0_BACKUP/backup + cp -r securedrop-workstation-dom0-config/ /usr/share/ + +If you customized clipboard or RPC policies, you may inspect the files in +``backup/etc/qubes-rpc/`` and ``backup/etc/qubes/`` to ensure that the +configurations in those files are re-applied to your new instance. + +.. note:: + Proceed with caution if overwriting files in ``/etc/qubes/`` and + ``/etc/qubes-rpc/`` with their counterparts from your backup file, since this + can have unintended consequences, in particular if there are configuration + differences between your old and new installation. + +Reinstall SecureDrop Workstation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Follow the :doc:`installation instructions ` to download and verify +the SecureDrop Workstation rpm to a network-attached VM and copy it to ``dom0``. + +.. note:: + If your installation is recent, your backup archive may contain the current + version of the rpm, in which case you can skip the above steps and move + straight to installing the rpm. + Use ``rpm -qi securedrop-workstation.rpm`` to compare the version with the + latest version at ``https://yum.securedrop.org/workstation/dom0/f25/`` + +Once you have a valid .rpm file in ``dom0``, install the .rpm by running: + + .. code-block:: sh + + sudo dnf install securedrop-workstation.rpm + +Copy the previous SecureDrop Workstation configuration into place: + + .. code-block:: sh + + cp -r $DOM0_BACKUP/backup/usr/share/securedrop-workstation-dom0-config \ + /usr/share/ + +Verify that the configuration is valid: + + .. code-block:: sh + + sdw-admin --validate + +Finally, reinstall SecureDrop Workstation: + + .. code-block:: sh + + sdw-admin --apply diff --git a/docs/index.rst b/docs/index.rst index d0abd8b..d526ac8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,7 +40,7 @@ against malware and other security risks. It is built on Qubes OS and requires a admin/known_issues admin/upgrading_to_fedora_33 admin/workstation_architecture - + admin/backup * :ref:`genindex` * :ref:`search` From 3a320ecc2a142212acc87f3e1c045b51bc0ffe6e Mon Sep 17 00:00:00 2001 From: ro Date: Tue, 8 Jun 2021 17:02:29 -0400 Subject: [PATCH 2/2] Avoid backing up dom0; incorporate review feedback. --- docs/admin/backup.rst | 131 +++++++++++++++++------------------------ docs/admin/install.rst | 2 + 2 files changed, 57 insertions(+), 76 deletions(-) diff --git a/docs/admin/backup.rst b/docs/admin/backup.rst index d91c1cd..15bde4f 100644 --- a/docs/admin/backup.rst +++ b/docs/admin/backup.rst @@ -8,54 +8,53 @@ that allows for backup and restoration of user-specified VMs. To perform backups, you will need: - - an encrypted storage medium - - a secure place to store backup credentials + - a LUKS-encrypted external hard drive, with at least 50GB space + - a secure place to store backup credentials (such as a password manager + on your primary laptop) Backup ------ -Prepare files in ``dom0`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +Preserve files from ``dom0`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Files outside the ``dom0`` home folder aren't normally backed up by the -Qubes backup tool. Preserve key configuration files by coping them to the -home directory. +Preserve key configuration files by coping them into the +``vault`` VM. In a ``dom0`` Terminal via **Q ▸ Terminal Emulator**: .. code-block:: sh - mkdir ~/backup/ - cp -r /usr/share/securedrop-workstation-dom0-config/ ~/backup/ + cd /usr/share/securedrop-workstation-dom0-config + qvm-copy-to-vm vault {config.json,sd-journalist.sec} -If you have customized :doc:`clipboard access ` -to SecureDrop Workstation, or have made any other customizations -involving RPC policies, back up related configuration files: +Open a ``vault`` Terminal and verify that the files were copied successfully: .. code-block:: sh + + head -n1 ~/QubesIncoming/dom0/sd-journalist.sec # line contains "BEGIN PRIVATE KEY BLOCK" + grep -q descriptor ~/QubesIncoming/dom0/config.json && echo OK # line is "OK" - mkdir -p ~/backup/etc/qubes - mkdir ~/backup/etc/qubes-rpc - cp -a /etc/qubes/* ~/backup/etc/qubes/ - cp -a /etc/qubes-rpc/* ~/backup/etc/qubes-rpc +.. note:: + If you have made advanced customizations to your Qubes Workstation, + you may need to back up additional components of ``dom0``. Refer to + the `Qubes documentation `_ + or contact Support. Back up SecureDrop Workstation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Ensure your storage medium is plugged in, attached to a VM, and mounted. -(LUKS-encrypted storage media may be attached to ``sd-usb``, or you may use a custom -VM of your choosing, if you are relying on another form of encryption such as -Veracrypt). +Ensure your storage medium is plugged in, attached to ``sd-devices``, +and unlocked. Navigate to **Q ▸ System Tools ▸ Backup Qubes**, and move all VMs from "Selected" to "Available" by pressing the ``<<`` button. To target a VM for backup, highlight it and move it into the "Selected" -column by pressing the ``>`` button. Select the following VMs: +column by pressing the ``>`` button. Select: - - ``dom0`` - - ``vault`` - - any customized VMs that you wish to preserve. +- the ``vault`` VM +- any customized VMs that you may wish to preserve. You do not need to back up the ``sd-`` VMs. @@ -85,84 +84,57 @@ Reinstall QubesOS To restore SecureDrop Workstation, follow our :doc:`pre-install tasks ` to provision a QubesOS system complete with -updated base templates. - -.. note:: - If you backed up a number of custom VMs, during the installer, you may opt - to un-select "create default application qubes (personal, work, untrusted, vault)". - -Manage Unused VMs -~~~~~~~~~~~~~~~~~ - -If you installed all default application VMs, remove the ``vault`` VM, since we -will replace it with the version in our backup. - - .. code-block:: sh - - qvm-prefs --set vault installed_by_rpm False - qvm-remove vault +updated base templates. This time, during the installation wizard, un-check +``create default application qubes (personal, work, untrusted, vault)``. Restore Backup ~~~~~~~~~~~~~~ Plug in your backup medium and unlock it as during the backup. By default -on a new system, your peripheral devices will be managed by ``sys-usb``. -(For non-LUKS-based encryption media, you will need to install and configure the -appropriate software, either in ``sys-usb`` or in another VM). +on a new system, your peripheral devices will be managed by a VM called +``sys-usb``. Navigate to **Q ▸ System Tools ▸ Restore Backup**, and enter the location of the backup file. You do not need to adjust the default Restore options, unless you have made customizations to the backup. Enter the -decryption/verification passphrase, and proceed to restore the backup. +decryption/verification passphrase, and proceed to restoring the available +qubes (which should include the ``vault`` VM). -Your ``vault`` VM will be restored. - -The contents of the previous ``dom0`` will be backed up to a folder in the -new ``dom0`` home directory called ``home-restore-/dom0-home/user``. -In this guide we will refer to that location as ``$DOM0_BACKUP``. +Reinstall SecureDrop Workstation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Open a terminal via **Q ▸ Terminal Emulator**: +Create a VM called ``work`` with default networking settings: .. code-block:: sh - cd $DOM0_BACKUP/backup - cp -r securedrop-workstation-dom0-config/ /usr/share/ - -If you customized clipboard or RPC policies, you may inspect the files in -``backup/etc/qubes-rpc/`` and ``backup/etc/qubes/`` to ensure that the -configurations in those files are re-applied to your new instance. + qvm-create -l blue work -.. note:: - Proceed with caution if overwriting files in ``/etc/qubes/`` and - ``/etc/qubes-rpc/`` with their counterparts from your backup file, since this - can have unintended consequences, in particular if there are configuration - differences between your old and new installation. +Then, :ref:`download and verify ` the SecureDrop Workstation +.rpm to the ``work`` VM and copy it to ``dom0``. -Reinstall SecureDrop Workstation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Once you have a valid .rpm file in ``dom0``, install the .rpm by running: -Follow the :doc:`installation instructions ` to download and verify -the SecureDrop Workstation rpm to a network-attached VM and copy it to ``dom0``. + .. code-block:: sh -.. note:: - If your installation is recent, your backup archive may contain the current - version of the rpm, in which case you can skip the above steps and move - straight to installing the rpm. - Use ``rpm -qi securedrop-workstation.rpm`` to compare the version with the - latest version at ``https://yum.securedrop.org/workstation/dom0/f25/`` + sudo dnf install securedrop-workstation.rpm -Once you have a valid .rpm file in ``dom0``, install the .rpm by running: +Retrieve the previous SecureDrop Workstation configuration from the ``vault`` +VM: .. code-block:: sh - sudo dnf install securedrop-workstation.rpm + qvm-run --pass-io vault "cat QubesIncoming/dom0/sd-journalist.sec > /tmp/sd-journalist.sec" + qvm-run --pass-io vault "cat QubesIncoming/dom0/config.json > /tmp/config.json" + +Optionally, inspect each file before proceeding. The first +file should be an ASCII-armored GPG private key file, and the second is a +one-line file with the format ``ONIONADDRESS:descriptor:x25519:AUTHTOKEN``. -Copy the previous SecureDrop Workstation configuration into place: +Copy both files into place: .. code-block:: sh - cp -r $DOM0_BACKUP/backup/usr/share/securedrop-workstation-dom0-config \ - /usr/share/ + sudo cp /tmp{sd-journalist.sec,config.json} /usr/share/securedrop-workstation-dom0-config/ Verify that the configuration is valid: @@ -170,6 +142,13 @@ Verify that the configuration is valid: sdw-admin --validate +If the above command does not produce any errors, the configuration is valid, +and you may remove the configuration files from the ``vault`` VM: + + .. code-block:: sh + + qvm-run vault "rm QubesIncoming/dom0/{config.json,sd-journalist.sec}" + Finally, reinstall SecureDrop Workstation: .. code-block:: sh diff --git a/docs/admin/install.rst b/docs/admin/install.rst index 8a8d021..f804474 100644 --- a/docs/admin/install.rst +++ b/docs/admin/install.rst @@ -281,6 +281,8 @@ In order to copy a journalist's login credentials: - Close the application window and shut down the ``vault`` VM (using the Qube widget in the upper right panel). +.. _download_rpm: + Download and install SecureDrop Workstation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~