diff --git a/docs/index.rst b/docs/index.rst index 06a16c1ed7f..f7927bdebcf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,6 +83,7 @@ anonymous sources. getting_support v3_services update_bios + upgrade_to_tails_4 offboarding decommission @@ -91,6 +92,7 @@ anonymous sources. :name: upgradetoc :maxdepth: 2 + upgrade/1.4.1_to_1.5.0.rst upgrade/1.4.0_to_1.4.1.rst upgrade/1.3.0_to_1.4.0.rst upgrade/1.2.2_to_1.3.0.rst diff --git a/docs/upgrade/1.0.0_to_1.1.0.rst b/docs/upgrade/1.0.0_to_1.1.0.rst index 06c4ac190df..1a0287be50b 100644 --- a/docs/upgrade/1.0.0_to_1.1.0.rst +++ b/docs/upgrade/1.0.0_to_1.1.0.rst @@ -60,109 +60,8 @@ Finally, run the following commands: :: ./securedrop-admin setup ./securedrop-admin tailsconfig -.. _upgrade_to_tails_4: +.. include:: ../upgrade_to_tails_4.rst -Upgrading workstations to Tails 4 ---------------------------------- - -.. important:: - - Before upgrading your *Admin Workstation* and your *Journalist Workstation* - to Tails 4, you must first ensure that the version of the SecureDrop code on - the workstation (which is used for administrative tasks and for configuring - the Tails desktop) is at 1.1.0 or a later version. - - If unsure, you can always run the ``git status`` command in the - ``~/Persistent/securedrop`` directory to determine the current version. If - the output is not "HEAD detached at 1.1.0" or a later version, you are *not* - ready to proceed with the upgrade to Tails 4, and you must first update the - workstation using the procedure described in the previous section. - -As a precaution, we recommend backing up your workstations before the upgrade -to Tails 4. See our :doc:`Workstation Backup Guide <../backup_workstations>` for -more information. We also recommend that you keep a USB drive running Tails 3.16 -on hand in case you need to revert. - -Once you have created the backups, create a *Tails 4 Primary USB* which you will -use to upgrade your workstation. Follow the -`instructions on the Tails website `__ -to create a fresh Tails drive on a computer running Windows, Mac, or Linux. - -Boot the *Tails 4 Primary USB* on the air-gapped computer you use as the *Secure -Viewing Station*, and follow the instructions for `manually upgrading from -another Tails `__ -to upgrade each workstation USB in turn. This procedure preserves the persistent -storage volume of each USB drive you upgrade to Tails 4. - -Boot each workstation into Tails 4 to verify that the upgrade was successful. On -the *Admin* and *Journalist Workstations*, set an administrator password on the -Tails welcome screen, and update the SecureDrop environment using the following -commands: :: - - cd ~/Persistent/securedrop - ./securedrop-admin setup - ./securedrop-admin tailsconfig - -During the ``./securedrop-admin setup`` step, Tails will prompt you if you want -to install a set of packages every time you start Tails. These packages are only -required for the setup process, so you can safely click **Install Only Once**. - -.. important:: - - Until you run these commands, the SecureDrop shortcuts on the Tails desktop - will not work, and the graphical updater will no longer report available - updates for the SecureDrop code on your workstation. - -No additional configuration is required for the *Secure Viewing Station*. - -If you experience difficulties with this upgrade, please do not hesitate to -contact us using any of the methods below. If the upgrade failed and you need -to restore from a backup, see our :ref:`guide for restoring workstations `. -Make sure you restore to a Tails drive using Tails 3.16 before attempting -another upgrade to Tails 4. - -Troubleshooting ``securedrop-admin`` ------------------------------------- - -This release migrates the ``securedrop-admin`` command to Python 3, which is -necessary because the Python 2 series reaches end-of-life on January 1, 2020. -The ``securedrop-admin setup`` step normally should take care of all the -required changes. - -If you see error messages when running ``securedrop-admin`` or -``securedrop-admin setup``, we recommend the following: - -- Ensure that you are running version 1.1.0 of SecureDrop on your workstation, - by running the command ``git status`` in your ``~/Persistent/securedrop`` - directory. If the output is not "HEAD detached at 1.1.0", perform a - :ref:`manual upgrade to SecureDrop 1.1.0 on your workstation `. - -- Check your network connection on your workstation. The - ``securedrop-admin setup`` command requires a working Tor connection. - -- Make sure that you have `set an admin password `__ - on the Tails welcome screen. - -If this does not solve the problem, clear out any existing Python environments -on your workstation by following these steps: - -- Change into the directory ``~/Persistent/securedrop/admin``. - -- Run the following commands from within this directory (make sure to type them - exactly as shown, as this is a destructive operation): - -.. code:: bash - - rm -r .venv - rm -r .venv3 - -- Change back into the ``~/Persistent/securedrop`` directory. - -- Run ``./securedrop-admin setup``. If the command completes without errors, - run the ``./securedrop-admin tailsconfig`` command. - -If you continue to experience difficulties, please contact us using any of the -methods below. Getting Support --------------- diff --git a/docs/upgrade/1.1.0_to_1.2.0.rst b/docs/upgrade/1.1.0_to_1.2.0.rst index 77024b5d713..ae38112f65d 100644 --- a/docs/upgrade/1.1.0_to_1.2.0.rst +++ b/docs/upgrade/1.1.0_to_1.2.0.rst @@ -57,7 +57,7 @@ prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. .. include:: ../includes/always-backup.txt diff --git a/docs/upgrade/1.2.0_to_1.2.1.rst b/docs/upgrade/1.2.0_to_1.2.1.rst index b50169e4722..0e793e9d466 100644 --- a/docs/upgrade/1.2.0_to_1.2.1.rst +++ b/docs/upgrade/1.2.0_to_1.2.1.rst @@ -57,7 +57,7 @@ prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. Getting Support --------------- diff --git a/docs/upgrade/1.2.1_to_1.2.2.rst b/docs/upgrade/1.2.1_to_1.2.2.rst index 843c82d906a..994cc10d3c7 100644 --- a/docs/upgrade/1.2.1_to_1.2.2.rst +++ b/docs/upgrade/1.2.1_to_1.2.2.rst @@ -64,7 +64,7 @@ prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. Getting Support --------------- diff --git a/docs/upgrade/1.2.2_to_1.3.0.rst b/docs/upgrade/1.2.2_to_1.3.0.rst index 4bfe26753c1..7a169eb58bc 100644 --- a/docs/upgrade/1.2.2_to_1.3.0.rst +++ b/docs/upgrade/1.2.2_to_1.3.0.rst @@ -75,7 +75,7 @@ graphical prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. .. include:: ../includes/always-backup.txt diff --git a/docs/upgrade/1.3.0_to_1.4.0.rst b/docs/upgrade/1.3.0_to_1.4.0.rst index b531d964a47..2616f5d5ee2 100644 --- a/docs/upgrade/1.3.0_to_1.4.0.rst +++ b/docs/upgrade/1.3.0_to_1.4.0.rst @@ -72,7 +72,7 @@ graphical prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. These instructions will be removed from a future version of this documentation. diff --git a/docs/upgrade/1.4.0_to_1.4.1.rst b/docs/upgrade/1.4.0_to_1.4.1.rst index e13585cb57f..6e72b9b515d 100644 --- a/docs/upgrade/1.4.0_to_1.4.1.rst +++ b/docs/upgrade/1.4.0_to_1.4.1.rst @@ -69,7 +69,7 @@ graphical prompts to update to the latest version. to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving security updates, and is no longer supported by the SecureDrop team. Please see our - :ref:`instructions for upgrading to Tails 4 `. + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. These instructions will be removed from a future version of this documentation. diff --git a/docs/upgrade/1.4.1_to_1.5.0.rst b/docs/upgrade/1.4.1_to_1.5.0.rst new file mode 100644 index 00000000000..9a0960bfbac --- /dev/null +++ b/docs/upgrade/1.4.1_to_1.5.0.rst @@ -0,0 +1,83 @@ +Upgrade from 1.4.1 to 1.5.0 +=========================== + +Automatic server upgrades +------------------------- +As with previous releases, your servers will be upgraded to the latest version +of SecureDrop automatically within 24 hours of the release. + +Updating Workstations to SecureDrop 1.5.0 +----------------------------------------- + +Using the graphical updater +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +On the next boot of your SecureDrop *Journalist* and *Admin Workstations*, +the *SecureDrop Workstation Updater* will alert you to workstation updates. You +must have `configured an administrator password `_ +on the Tails welcome screen in order to use the graphical updater. + +Perform the update to 1.5.0 by clicking "Update Now": + +.. image:: ../images/securedrop-updater.png + +Performing a manual update +~~~~~~~~~~~~~~~~~~~~~~~~~~ +If the graphical updater fails and you want to perform a manual update instead, +first delete the graphical updater's temporary flag file, if it exists (the +``.`` before ``securedrop`` is not a typo): :: + + rm ~/Persistent/.securedrop/securedrop_update.flag + +This will prevent the graphical updater from attempting to re-apply the failed +update and has no bearing on future updates. You can now perform a manual +update by running the following commands: :: + + cd ~/Persistent/securedrop + git fetch --tags + gpg --keyserver hkps://keys.openpgp.org --recv-key \ + "2224 5C81 E3BA EB41 38B3 6061 310F 5612 00F4 AD77" + git tag -v 1.5.0 + +The output should include the following two lines: :: + + gpg: using RSA key 22245C81E3BAEB4138B36061310F561200F4AD77 + gpg: Good signature from "SecureDrop Release Signing Key" + +Please verify that each character of the fingerprint above matches what is +on the screen of your workstation. If it does, you can check out the +new release: :: + + git checkout 1.5.0 + +.. important:: If you do see the warning "refname '1.5.0' is ambiguous" in the + output, we recommend that you contact us immediately at securedrop@freedom.press + (`GPG encrypted `__). + +Finally, run the following commands: :: + + ./securedrop-admin setup + ./securedrop-admin tailsconfig + +Upgrading Tails +--------------- +If you have already upgraded your workstations to the Tails 4 series, follow the +graphical prompts to update to the latest version. + +.. important:: + + If you are still running Tails 3.x on any workstation, we urge you to update + to the Tails 4 series as soon as possible. Tails 3.x is no longer receiving + security updates, and is no longer supported by the SecureDrop team. + Please see our + :doc:`instructions for upgrading to Tails 4 <../upgrade_to_tails_4>`. + + These instructions will be removed from a future version of this + documentation. + +Getting Support +--------------- + +Should you require further support with your SecureDrop installation, we are +happy to help! + +.. include:: ../includes/getting-support.txt diff --git a/docs/upgrade_to_tails_4.rst b/docs/upgrade_to_tails_4.rst new file mode 100644 index 00000000000..6091a224d41 --- /dev/null +++ b/docs/upgrade_to_tails_4.rst @@ -0,0 +1,59 @@ +Upgrading workstations to Tails 4 +--------------------------------- + +.. important:: + + Before upgrading your *Admin Workstation* and your *Journalist Workstation* + to Tails 4, you must first ensure that the version of the SecureDrop code on + the workstation (which is used for administrative tasks and for configuring + the Tails desktop) is at 1.1.0 or a later version. + + If unsure, you can always run the ``git status`` command in the + ``~/Persistent/securedrop`` directory to determine the current version. If + the output is not "HEAD detached at 1.1.0" or a later version, you are *not* + ready to proceed with the upgrade to Tails 4, and you must first update the + workstation using the procedure described in the previous section. + +As a precaution, we recommend backing up your workstations before the upgrade +to Tails 4. See our :doc:`Workstation Backup Guide <../backup_workstations>` for +more information. We also recommend that you keep a USB drive running Tails 3.16 +on hand in case you need to revert. + +Once you have created the backups, create a *Tails 4 Primary USB* which you will +use to upgrade your workstation. Follow the +`instructions on the Tails website `__ +to create a fresh Tails drive on a computer running Windows, Mac, or Linux. + +Boot the *Tails 4 Primary USB* on the air-gapped computer you use as the *Secure +Viewing Station*, and follow the instructions for `manually upgrading from +another Tails `__ +to upgrade each workstation USB in turn. This procedure preserves the persistent +storage volume of each USB drive you upgrade to Tails 4. + +Boot each workstation into Tails 4 to verify that the upgrade was successful. On +the *Admin* and *Journalist Workstations*, set an administrator password on the +Tails welcome screen, and update the SecureDrop environment using the following +commands: :: + + cd ~/Persistent/securedrop + ./securedrop-admin setup + ./securedrop-admin tailsconfig + +During the ``./securedrop-admin setup`` step, Tails will prompt you if you want +to install a set of packages every time you start Tails. These packages are only +required for the setup process, so you can safely click **Install Only Once**. + +.. important:: + + Until you run these commands, the SecureDrop shortcuts on the Tails desktop + will not work, and the graphical updater will no longer report available + updates for the SecureDrop code on your workstation. + +No additional configuration is required for the *Secure Viewing Station*. + +If you experience difficulties with this upgrade, please do not hesitate to +contact us using any of the methods below. If the upgrade failed and you need +to restore from a backup, see our :ref:`guide for restoring workstations `. +Make sure you restore to a Tails drive using Tails 3.16 before attempting +another upgrade to Tails 4. +