Add backup and restore instructions

docs/admin/backup.rst

@@ -0,0 +1,156 @@
+Backup and Restore
+==================
+
+.. include:: ../includes/top-warning.rst
+
+QubesOS has a `backup utility <https://www.qubes-os.org/doc/backup-restore/>`_ 
+that allows for backup and restoration of user-specified VMs. 
+
+To perform backups, you will need:
+
+ - 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 
+------
+
+Preserve files from ``dom0``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Preserve key configuration files by coping them into the 
+``vault`` VM.
+
+In a ``dom0`` Terminal via **Q ▸ Terminal Emulator**:
+
+  .. code-block:: sh
+
+    cd /usr/share/securedrop-workstation-dom0-config
+    qvm-copy-to-vm vault {config.json,sd-journalist.sec}
+
+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"
+
+.. 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 <https://www.qubes-os.org/doc/backup-restore/>`_
+  or contact Support.
+
+Back up SecureDrop Workstation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 ``vault`` VM
+- any customized VMs that you may 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 <https://www.qubes-os.org/doc/backup-restore/>`_.
+
+Restore
+-------
+
+Reinstall QubesOS
+~~~~~~~~~~~~~~~~~
+
+To restore SecureDrop Workstation, follow our 
+:doc:`pre-install tasks <install>` to provision a QubesOS system complete with
+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 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 restoring the available
+qubes (which should include the ``vault`` VM).
+
+Reinstall SecureDrop Workstation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a VM called ``work`` with default networking settings: 
+
+  .. code-block:: sh
+
+    qvm-create -l blue work
+
+Then, :ref:`download and verify <download_rpm>` the SecureDrop Workstation 
+.rpm to the ``work`` VM and copy it to ``dom0``.
+
+Once you have a valid .rpm file in ``dom0``, install the .rpm by running:
+
+  .. code-block:: sh
+
+    sudo dnf install securedrop-workstation.rpm
+
+Retrieve the previous SecureDrop Workstation configuration from the ``vault``
+VM:
+
+  .. code-block:: sh
+
+    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 both files into place:
+
+  .. code-block:: sh
+
+    sudo cp /tmp{sd-journalist.sec,config.json} /usr/share/securedrop-workstation-dom0-config/
+
+Verify that the configuration is valid:
+
+  .. code-block:: sh
+
+    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
+
+    sdw-admin --apply

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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`