Fix update_version, filepaths in backup-restore commands, and move in…

…cludes directive back into migration doc since it is now only used once.

docs/backup_and_restore.rst

@@ -122,7 +122,7 @@ recovery purposes), see
 
 If you are reinstalling SecureDrop and then restoring from a backup (for
 example, for hardware migration, operating system upgrade, or disaster
-recovery purposes), see :ref:`Migrating <migrating>`.
+recovery purposes), see :ref:`Migrating Using a Backup <migrating>`.
 
 For other data recovery scenarios, see
 :ref:`Additional Information <additional_restore_info>` or `contact Support`_.
@@ -143,23 +143,20 @@ To restore an existing instance to a previous state, run the command:
 Make sure to replace ``sd-backup-2020-07-22--01-06-25.tar.gz`` with the filename
 for your backup archive.
 
-This command attempts to  restore submissions, source and journalist accounts,
+This command attempts to restore submissions, source and journalist accounts,
 and configuration details for the onion services used by the web interfaces and
-SSH (if configured) to their state at the time of the backup.
+SSH (if configured).
 
-If your backup contains v2 and v3 onion service configuration
-details, but your instance has since been reconfigured to use v3 onion
-services only, the restore command will restore only the v3 onion service
-configuration.
-
-.. note:: You cannot restore the onion service configuration from a v2-only
-  backup onto a v3-only server -  but you can restore submissions and account
-  data using the ``--preserve-tor-config`` argument. See :ref:`Data-only Restores <additional_restore_info>` for more information.
+.. note:: You cannot restore v2 onion service configurations to a v3-only server 
+   (this includes any SecureDrop installation based on Ubuntu 20.04). If a 
+   restore operation would leave you without a valid onion service configuration, 
+   the restore script will fail with an error. In this case, you can still perform 
+   a data-only restore. See :ref:`Data-only Restores <additional_restore_info>` for more information.
 
 .. _migrating:
 
-Migrating to a New Instance Using a Backup
--------------------------------------------
+Migrating Using a Backup
+-------------------------
 
 Moving a SecureDrop instance to new hardware involves:
 
@@ -181,7 +178,158 @@ the old instance and preserved in the backup:
 Migrating Using a V2+V3 or V3-Only Backup
 '''''''''''''''''''''''''''''''''''''''''
 
-.. include:: includes/v3_backup_steps_common.rst
+.. note::  The instructions below assume that you are using the same *Admin Workstation*
+   that was used to manage your old instance. If you are using a new *Admin
+   Workstation* you will need to copy the directory ``~amnesia/Persistent/securedrop``
+   from the old workstation to the new workstation (using a *Transfer Device*)
+   before proceeding.
+
+#. If you have not already done so, :ref:`back up the existing installation <backing_up>`. 
+   The instructions below assume that the backup has been created 
+   and renamed ``sd-backup-old.tar.gz``.
+
+#. Move the existing *Admin Workstation* SecureDrop code out of the way, by
+   opening a Terminal via **Applications > System Tools > Terminal** and
+   running the command:
+
+   .. code:: sh
+
+      mv ~/Persistent/securedrop ~/Persistent/sd.bak
+
+#. Move the existing *Admin Workstation* SSH configuration out of the way via
+   the Terminal, using the commands:
+
+   .. code:: sh
+
+       mv ~/.ssh/config ~/.ssh/config.bak
+       mv ~/.ssh/known_hosts ~/.ssh/known_hosts.bak
+
+#. Re-clone the SecureDrop repository to the *Admin Workstation* using the following 
+   Terminal commands:
+
+   .. code:: sh
+
+      cd ~/Persistent
+      git clone https://github.com/freedomofpress/securedrop
+
+#. Verify that the current release tag was signed with the release signing key:
+
+   .. code:: sh
+
+      cd ~/Persistent/securedrop/
+      git fetch --tags
+      git tag -v 1.7.1
+
+   The output should include the following two lines:
+
+   .. code:: sh
+
+      gpg:                using RSA key 22245C81E3BAEB4138B36061310F561200F4AD77
+      gpg: Good signature from "SecureDrop Release Signing Key"
+
+
+   .. important::
+      If you do not see the message above, signature verification has failed
+      and you should **not** proceed with the installation. If this happens,
+      please contact us at [email protected].
+
+
+   Verify that each character of the fingerprint matches what is on the
+   screen of your workstation. If it does, you can check out the new release:
+
+   .. code:: sh
+
+      git checkout 1.7.1
+
+   .. important::
+      If you see the warning ``refname '1.7.1' is ambiguous`` in the
+      output, we recommend that you contact us immediately at
+      [email protected] 
+      (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).
+
+#. Copy the old instance's configuration files and backup from 
+   ``~/Persistent/sd.bak`` into ``~/Persistent/securedrop`` using the following 
+   Terminal commands:
+
+   .. code:: sh
+
+      cd ~/Persistent/securedrop
+      export SD_OLD="~/Persistent/sd.bak/install_files/ansible-base"
+      export SD_NEW="~/Persistent/securedrop/install_files/ansible-base"
+      cp $SD_OLD/group_vars/all/site-specific $SD_NEW/group_vars/all/
+      cp $SD_OLD/tor_v3_keys.json $SD_NEW/
+      cp $SD_OLD/sd-backup-old.tar.gz $SD_NEW/
+
+   You will also need to copy the old instance's *Submission Public Key*,
+   *OSSEC Alert Public Key*, and, if configured, the *Journalist Alert Public Key*.
+   Assuming that these are named ``SecureDrop.asc``, ``ossec.asc``, and
+   ``journalist.asc`` respectively, run the following commands:
+
+   .. code:: sh
+
+      cp $SD_OLD/SecureDrop.asc $SD_NEW/
+      cp $SD_OLD/ossec.asc $SD_NEW/
+      cp $SD_OLD/journalist.asc $SD_NEW/
+
+#. *(Optional):* If your old instance was configured to provide the *Source
+   Interface* via HTTPS, you should also copy across the certificate, certificate
+   key, and chain file. Assuming that these are named ``sd.crt``, ``sd.key``, and
+   ``ca.crt`` respectively, run the following commands:
+
+   .. code:: sh
+
+      cp $SD_OLD/sd.{crt,key} $SD_NEW/
+      cp $SD_OLD/ca.crt $SD_NEW/
+
+#. Install Ubuntu 20.04 on the *Application* and *Monitor Servers*, following
+   the :doc:`server setup instructions<servers>` to install with the correct
+   settings, test connectivity, and set up SSH keys to allow for
+   *Admin Workstation* access.
+
+#. Reinstall SecureDrop on the servers, following the :doc:`installation
+   instructions <install>`. During the configuration stage
+   (``./securedrop-admin sdconfig``), the values will be prepopulated based on
+   the old instance's configuration. Press **Enter** to accept each value,
+   except when you are asked if you want to enable v2 onion services: there,
+   ensure the answer is ``no``.
+
+   Proceed through the installation, finishing with
+   ``./securedrop-admin tailsconfig``. If SSH-over-Tor is configured, run
+   ``ssh app uptime`` and ``ssh mon uptime``  in the Terminal to verify SSH
+   connectivity.
+
+#. Restore from the old instance's backup (e.g. ``sd-backup-old.tar.gz``) using
+   the Terminal command:
+
+   .. code:: sh
+
+       ./securedrop-admin restore sd-backup-old.tar.gz
+
+   The restore task will proceed for some time, removing v2 services if a v2+v3
+   backup was used, and then will fail with the message:
+
+   .. code-block:: none
+
+     ssh_exchange_identification: Connection closed by remote host
+
+   during the ``Wait for Tor to reload`` task. This is expected; the
+   *Application Server*'s SSH onion service address was updated to the old
+   instance's address during the restore process, leaving it temporarily
+   unreachable.
+
+#. Copy the old instance's v3 onion service details into place on the
+   *Admin Workstation* and repair SSH access using the Terminal commands:
+
+   .. code:: sh
+
+      cd ~/Persistent/securedrop
+      cp $SD_OLD/app-{journalist,ssh}.auth_private $SD_NEW/
+      cp $SD_OLD/app-sourcev3-ths $SD_NEW/
+      ./securedrop-admin tailsconfig
+
+#. :doc:`Test the new instance <test_the_installation>` to verify that the
+   web interfaces are available and the servers can be reached via SSH.
+
 
 .. _migrate_v2:
 
@@ -199,7 +347,9 @@ source accounts, and journalist accounts. To do so, follow the steps below:
   from the old workstation to the new workstation (using a *Transfer Device*)
   before proceeding.
 
-#. If you have not already done so, :ref:`back up the existing installation <backing_up>`. The instructions below assume that the backup has been created and renamed ``sd-backup-old.tar.gz``.
+#. If you have not already done so, :ref:`back up the existing installation <backing_up>`. 
+   The instructions below assume that the backup has been created and 
+   renamed ``sd-backup-old.tar.gz``.
 
 #. Move the existing *Admin Workstation* SecureDrop code out of the way, by
    opening a Terminal via **Applications > System Tools > Terminal** and
@@ -242,10 +392,9 @@ source accounts, and journalist accounts. To do so, follow the steps below:
 
 
    .. important::
-      If you do not see the message above, signature verification has failed
-      and you should **not** proceed with the installation. If this happens,
-      please contact us at [email protected].
-
+       If you do not see the message above, signature verification has failed
+       and you should **not** proceed with the installation. If this happens,
+       please contact us at [email protected].
 
    Verify that each character of the fingerprint matches what is on the
    screen of your workstation. If it does, you can check out the new release:
@@ -254,6 +403,7 @@ source accounts, and journalist accounts. To do so, follow the steps below:
 
       git checkout 1.7.1
 
+
    .. important::
       If you see the warning ``refname '1.7.1' is ambiguous`` in the
       output, we recommend that you contact us immediately at
@@ -266,18 +416,18 @@ source accounts, and journalist accounts. To do so, follow the steps below:
       cd ~/Persistent/securedrop
       export SD_OLD="~/Persistent/sd.bak/install_files/ansible-base"
       export SD_NEW="~/Persistent/securedrop/install_files/ansible-base"
-      cp $SD_OLD/group_vars/all/site-specific $SD_NEW/group_vars/all/site-specific
-      cp $SD_OLD/sd-backup-old.tar.gz $SD_NEW/sd-backup-old.tar.gz
+      cp $SD_OLD/group_vars/all/site-specific $SD_NEW/group_vars/all/
+      cp $SD_OLD/sd-backup-old.tar.gz $SD_NEW/
 
    You will also need to copy the old instance's *Submission Public Key*,
-   *Ossec Alert Public Key*, and, if configured, the *Journalist Alert Public Key*.
+   *OSSEC Alert Public Key*, and, if configured, the *Journalist Alert Public Key*.
    Assuming that these are named ``SecureDrop.asc``, ``ossec.asc``, and
    ``journalist.asc`` respectively, run the following commands:
 
    .. code:: sh
 
-      cp $SD_OLD/SecureDrop.asc $SD_NEW/SecureDrop.asc
-      cp $SD_OLD/ossec.asc $SD_NEW/ansible-base/ossec.asc
+      cp $SD_OLD/SecureDrop.asc $SD_NEW/
+      cp $SD_OLD/ossec.asc $SD_NEW/
 
 #. Install Ubuntu 20.04 on the *Application* and *Monitor Servers*, following
    the :doc:`server setup instructions<servers>` to install with the correct
@@ -318,8 +468,8 @@ Additional Information
 
 .. _restore_preserve_tor_config:
 
-Restore Data Without Restoring Tor Configuration
-''''''''''''''''''''''''''''''''''''''''''''''''
+Data-Only Restores
+''''''''''''''''''
 
 The ``restore`` command normally restores both the data and the Tor
 configuration of an instance, including the .onion URLs for your instance.