From 02c47987089e810dea091903efe581d969788f49 Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Wed, 18 Sep 2024 12:39:36 -0400 Subject: [PATCH 1/2] Bump version to 2.10.0 and add upgrade guide --- .../admin/installation/set_up_admin_tails.rst | 6 +- docs/admin/maintenance/backup_and_restore.rst | 12 +- .../admin/maintenance/update_workstations.rst | 6 +- docs/conf.py | 2 +- docs/index.rst | 1 + docs/upgrade/2.8.0_to_2.9.0.rst | 2 - docs/upgrade/2.9.0_to_2.10.0.rst | 136 ++++++++++++++++++ 7 files changed, 150 insertions(+), 15 deletions(-) create mode 100644 docs/upgrade/2.9.0_to_2.10.0.rst diff --git a/docs/admin/installation/set_up_admin_tails.rst b/docs/admin/installation/set_up_admin_tails.rst index 22e9cd72f..8d115146d 100644 --- a/docs/admin/installation/set_up_admin_tails.rst +++ b/docs/admin/installation/set_up_admin_tails.rst @@ -139,7 +139,7 @@ signed with the release signing key: cd ~/Persistent/securedrop/ git fetch --tags - git tag -v 2.9.0 + git tag -v 2.10.0 The output should include the following two lines: @@ -160,9 +160,9 @@ screen of your workstation. If it does, you can check out the new release: .. code:: sh - git checkout 2.9.0 + git checkout 2.10.0 -.. important:: If you see the warning ``refname '2.9.0' is ambiguous`` in the +.. important:: If you see the warning ``refname '2.10.0' is ambiguous`` in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). diff --git a/docs/admin/maintenance/backup_and_restore.rst b/docs/admin/maintenance/backup_and_restore.rst index 279475ef8..7422d9797 100644 --- a/docs/admin/maintenance/backup_and_restore.rst +++ b/docs/admin/maintenance/backup_and_restore.rst @@ -229,7 +229,7 @@ Migrating Using a V2+V3 or V3-Only Backup cd ~/Persistent/securedrop/ git fetch --tags - git tag -v 2.9.0 + git tag -v 2.10.0 The output should include the following two lines: @@ -250,10 +250,10 @@ Migrating Using a V2+V3 or V3-Only Backup .. code:: sh - git checkout 2.9.0 + git checkout 2.10.0 .. important:: - If you see the warning ``refname '2.9.0' is ambiguous`` in the + If you see the warning ``refname '2.10.0' is ambiguous`` in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). @@ -472,7 +472,7 @@ source accounts, and journalist accounts. To do so, follow the steps below: cd ~/Persistent/securedrop/ git fetch --tags - git tag -v 2.9.0 + git tag -v 2.10.0 The output should include the following two lines: @@ -491,11 +491,11 @@ source accounts, and journalist accounts. To do so, follow the steps below: .. code:: sh - git checkout 2.9.0 + git checkout 2.10.0 .. important:: - If you see the warning ``refname '2.9.0' is ambiguous`` in the + If you see the warning ``refname '2.10.0' is ambiguous`` in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). diff --git a/docs/admin/maintenance/update_workstations.rst b/docs/admin/maintenance/update_workstations.rst index a2476f33e..75441fc0f 100644 --- a/docs/admin/maintenance/update_workstations.rst +++ b/docs/admin/maintenance/update_workstations.rst @@ -24,7 +24,7 @@ update by running the following commands: :: git fetch --tags gpg --keyserver hkps://keys.openpgp.org --recv-key \ "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3" - git tag -v 2.9.0 + git tag -v 2.10.0 The output should include the following two lines: :: @@ -37,9 +37,9 @@ on the screen of your workstation. A warning that the key is not certified is normal and expected. If the output includes the lines above, you can check out the new release: :: - git checkout 2.9.0 + git checkout 2.10.0 -.. important:: If you do see the warning "refname '2.9.0' is ambiguous" in the +.. important:: If you do see the warning "refname '2.10.0' is ambiguous" in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). diff --git a/docs/conf.py b/docs/conf.py index 3a16f2654..9ada885fe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ # built documents. # # The short X.Y version. -version = "2.9.0" +version = "2.10.0" # The full version, including alpha/beta/rc tags. # On the live site, this will be overridden to "stable" or "latest". release = os.environ.get("SECUREDROP_DOCS_RELEASE", version) diff --git a/docs/index.rst b/docs/index.rst index cecb755d8..616ae1396 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -151,6 +151,7 @@ Get Started :maxdepth: 2 :hidden: + upgrade/2.9.0_to_2.10.0.rst upgrade/2.8.0_to_2.9.0.rst upgrade/2.7.0_to_2.8.0.rst upgrade/2.6.1_to_2.7.0.rst diff --git a/docs/upgrade/2.8.0_to_2.9.0.rst b/docs/upgrade/2.8.0_to_2.9.0.rst index c5c0acdae..410e874de 100644 --- a/docs/upgrade/2.8.0_to_2.9.0.rst +++ b/docs/upgrade/2.8.0_to_2.9.0.rst @@ -1,5 +1,3 @@ -.. _latest_upgrade_guide: - Upgrade from 2.8.0 to 2.9.0 =========================== diff --git a/docs/upgrade/2.9.0_to_2.10.0.rst b/docs/upgrade/2.9.0_to_2.10.0.rst new file mode 100644 index 000000000..6cc7dbe69 --- /dev/null +++ b/docs/upgrade/2.9.0_to_2.10.0.rst @@ -0,0 +1,136 @@ +.. _latest_upgrade_guide: + +Upgrade from 2.9.0 to 2.10.0 +============================ + +Update Servers to SecureDrop 2.10.0 +----------------------------------- + +Servers running Ubuntu 20.04 will be updated to the latest version of SecureDrop +automatically within 24 hours of the release. + +Update Workstations to SecureDrop 2.10.0 and Tails 6 +---------------------------------------------------- +If you have not already upgraded to Tails 6 alogside the 2.8.0 release, +you should do so as part of this upgrade. Please note that the upgrade +from Tails 6 must be performed manually. If you have already upgraded +to Tails 6, you only need to complete Step 1 below. + +.. important:: We always recommend backing up your workstations prior to + an upgrade, but we *especially* recommend it before a major Tails version + bump. This upgrade is an excellent occasion to make sure you have fresh + backups for each of your Tails drives. See our :ref:`backup instructions ` + for more information. + +To upgrade your *Secure Viewing Station* Tails USB, follow our instructions +to :ref:`update Tails manually `. The *SVS* upgrade +to Tails 6 **must** be fully performed on an air-gapped machine. + +To upgrade your *Journalist Workstation* and *Admin Workstation* USB drives, +complete the following steps for each USB drive: + +1. Update to SecureDrop 2.10.0 using the graphical updater +2. Perform a manual upgrade to Tails 6 +3. Apply SecureDrop-specific configuration +4. Verify that the workstation works as expected. + +These steps are further explained below. If these steps fail unexpectedly, please get +in touch. + +Step 1: Update to SecureDrop 2.10.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 2.10.0 by clicking "Update Now": + +.. image:: ../images/securedrop-updater.png + +Fallback: Perform 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 \ + "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3" + git tag -v 2.10.0 + +The output should include the following two lines: :: + + gpg: using RSA key 2359E6538C0613E652955E6C188EDD3B7B22E6A3 + gpg: Good signature from "SecureDrop Release Signing Key " [unknown] + + +Please verify that each character of the fingerprint above matches what is +on the screen of your workstation. A warning that the key is not certified +is normal and expected. If the output includes the lines above, you can check +out the new release: :: + + git checkout 2.10.0 + +.. important:: If you do see the warning "refname '2.10.0' is ambiguous" in the + output, we recommend that you contact us immediately at securedrop@freedom.press + (`GPG encrypted `__). + +Finally, run the following commands: :: + + sudo apt update + ./securedrop-admin setup + ./securedrop-admin tailsconfig + +Step 2: Perform a manual upgrade to Tails 6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Because Tails 6 represents a major release, an automatic update from Tails 5 is +not possible. + +Follow our instructions to :ref:`update Tails manually `. + +Step 3: Apply SecureDrop-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Boot up the updated workstation, connect to the Tor network, and run the +following commands in a terminal: :: + + cd ~/Persistent/securedrop + sudo apt update + ./securedrop-admin setup + ./securedrop-admin tailsconfig + +You must run these commands on Tails 6 even if you have just run them on +Tails 5. This will create a Python virtual environment compatible with Tails 6 +and re-apply the SecureDrop-specific configuration on your workstation. + +Step 4: Verify that the workstation works as expected +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You should now see the SecureDrop Menu in the menu bar at the top: + +|The SecureDrop Menu| + +Note that the options listed in the menu will depend on whether +you are booting a *Journalist Workstation* or an *Admin Workstation*. +Confirm that all options work as expected. + +.. note:: Support for desktop shortcuts has been removed in Tails 6. + Use the *Securedrop Menu* to access all SecureDrop-related features. + +.. |The SecureDrop Menu| image:: ../images/securedrop_menu.png + :alt: The SecureDrop Menu, showing all available options. + +Getting Support +--------------- + +Should you require further support with your SecureDrop installation, we are +happy to help! + +.. include:: ../includes/getting-support.txt From d4782b809a32466e0ab5aa67711b8ff6413698aa Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Wed, 18 Sep 2024 12:40:35 -0400 Subject: [PATCH 2/2] Remove 2.5.x upgrade guides --- docs/index.rst | 2 - docs/upgrade/2.5.1_to_2.5.2.rst | 130 ---------------------------- docs/upgrade/2.5.2_to_2.6.0.rst | 146 -------------------------------- 3 files changed, 278 deletions(-) delete mode 100644 docs/upgrade/2.5.1_to_2.5.2.rst delete mode 100644 docs/upgrade/2.5.2_to_2.6.0.rst diff --git a/docs/index.rst b/docs/index.rst index 616ae1396..3808051f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -156,8 +156,6 @@ Get Started upgrade/2.7.0_to_2.8.0.rst upgrade/2.6.1_to_2.7.0.rst upgrade/2.6.0_to_2.6.1.rst - upgrade/2.5.2_to_2.6.0.rst - upgrade/2.5.1_to_2.5.2.rst Get Involved ^^^^^^^^^^^^ diff --git a/docs/upgrade/2.5.1_to_2.5.2.rst b/docs/upgrade/2.5.1_to_2.5.2.rst deleted file mode 100644 index 226a6c80a..000000000 --- a/docs/upgrade/2.5.1_to_2.5.2.rst +++ /dev/null @@ -1,130 +0,0 @@ -Upgrade from 2.5.1 to 2.5.2 -=========================== - -Update Servers to SecureDrop 2.5.2 ----------------------------------- -Servers running Ubuntu 20.04 will be updated to the latest version of SecureDrop -automatically within 24 hours of the release. - -Update Workstations to SecureDrop 2.5.2 ---------------------------------------- - -.. note:: - - If you encounter errors with the graphical updater, perform a - manual update. This will ensure that you have imported the new - `SecureDrop release signing key `_. - -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 2.5.2 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 \ - "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3" - git tag -v 2.5.2 - -The output should include the following two lines: :: - - gpg: using RSA key 2359E6538C0613E652955E6C188EDD3B7B22E6A3 - gpg: Good signature from "SecureDrop Release Signing Key " [unknown] - - -Please verify that each character of the fingerprint above matches what is -on the screen of your workstation. A warning that the key is not certified -is normal and expected. If the output includes the lines above, you can check -out the new release: :: - - git checkout 2.5.2 - -.. important:: If you do see the warning "refname '2.5.2' 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 - -Update Tails ------------- -Follow the graphical prompts to update to the latest version of the Tails -operating system on your *Admin* and *Journalist Workstations*. - -If you have not already done so, you must manually upgrade from the Tails 4 release -series to the Tails 5 series. - -Upgrade from Tails 4 to Tails 5 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. important:: - - You must upgrade your workstations to the latest version of SecureDrop by following - the steps above *before* upgrading to the Tails 5 series. You can verify the version - of SecureDrop by running ``git status`` in your ``~/Persistent/securedrop`` directory. - The output should include "HEAD detached at 2.5.2". - -The Tails 5 series is based on Debian 11 ("Bullseye"). Among the most noticeable -changes is the switch to a new frontend for GnuPG called Kleopatra. Once you -upgrade your *Secure Viewing Station*, you will need to use Kleopatra to open -``.gpg`` files. Please see our :ref:`Journalist Guide ` -for more information. - -You must perform the upgrade to Tails 5 manually. You need a blank USB drive -that you can install the latest release in the Tails 5 series on from scratch. -You will use this drive to upgrade your *Journalist Workstation(s)*, your -*Admin Workstation(s)*, and your *Secure Viewing Station(s)*. - -The persistent storage volumes of your USB drives will be migrated as part of -this upgrade, but we still highly recommend backing them up first. Follow the -steps for :ref:`updating Tails manually `. - -Fore each *Journalist* and *Admin Workstation*, perform the following additional -steps to complete the upgrade: - -1. Boot the USB drive -2. On the Tails welcome screen, unlock the persistent volume and configure an - administrator password -3. Open a terminal (**Applications ▸ Utilities ▸ Terminal**) -4. Run the following commands: - -:: - - cd ~/Persistent/securedrop/admin - rm -rf .venv3 - cd .. - ./securedrop-admin setup - -When prompted by Tails to "Install Only Once" or "Install Every Time", click -**Install Every Time** (this is a change from previous versions of Tails). - -.. include:: ../includes/backup-and-update-reminders.txt - - -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/2.5.2_to_2.6.0.rst b/docs/upgrade/2.5.2_to_2.6.0.rst deleted file mode 100644 index 8b6d47490..000000000 --- a/docs/upgrade/2.5.2_to_2.6.0.rst +++ /dev/null @@ -1,146 +0,0 @@ -Upgrade from 2.5.2 to 2.6.0 -=========================== - -Update Servers to SecureDrop 2.6.0 ----------------------------------- -Servers running Ubuntu 20.04 will be updated to the latest version of SecureDrop -automatically within 24 hours of the release. - -Update Workstations to SecureDrop 2.6.0 ---------------------------------------- - -Updating Tails and replacing short passphrases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before upgrading your Workstations to SecureDrop 2.6.0, we -strongly recommend that you first upgrade to Tails 5.14, which includes -important updates to disk encryption and passphrase hashing algorithms. - -We also recommend updating all other encrypted drives to LUKS2, and ensuring -you have strong passphrases. - -We have issued a Security Advisory, which provides detailed instructions for -updating the Workstations, as well as any other encrypted drives. You can find -that `advisory on the SecureDrop website. -`_ - - -Using the graphical updater -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - If you encounter errors with the graphical updater, perform a - manual update. This will ensure that you have imported the new - `SecureDrop release signing key `_. - -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 2.6.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 \ - "2359 E653 8C06 13E6 5295 5E6C 188E DD3B 7B22 E6A3" - git tag -v 2.6.0 - -The output should include the following two lines: :: - - gpg: using RSA key 2359E6538C0613E652955E6C188EDD3B7B22E6A3 - gpg: Good signature from "SecureDrop Release Signing Key " [unknown] - - -Please verify that each character of the fingerprint above matches what is -on the screen of your workstation. A warning that the key is not certified -is normal and expected. If the output includes the lines above, you can check -out the new release: :: - - git checkout 2.6.0 - -.. important:: If you do see the warning "refname '2.6.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 - -Update Tails ------------- -Follow the graphical prompts to update to the latest version of the Tails -operating system on your *Admin* and *Journalist Workstations*. - -If you have not already done so, you must manually upgrade from the Tails 4 release -series to the Tails 5 series. - -Upgrade from Tails 4 to Tails 5 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. important:: - - You must upgrade your workstations to the latest version of SecureDrop by following - the steps above *before* upgrading to the Tails 5 series. You can verify the version - of SecureDrop by running ``git status`` in your ``~/Persistent/securedrop`` directory. - The output should include "HEAD detached at 2.6.0". - -The Tails 5 series is based on Debian 11 ("Bullseye"). Among the most noticeable -changes is the switch to a new frontend for GnuPG called Kleopatra. Once you -upgrade your *Secure Viewing Station*, you will need to use Kleopatra to open -``.gpg`` files. Please see our :ref:`Journalist Guide ` -for more information. - -You must perform the upgrade to Tails 5 manually. You need a blank USB drive -that you can install the latest release in the Tails 5 series on from scratch. -You will use this drive to upgrade your *Journalist Workstation(s)*, your -*Admin Workstation(s)*, and your *Secure Viewing Station(s)*. - -The persistent storage volumes of your USB drives will be migrated as part of -this upgrade, but we still highly recommend backing them up first. Follow the -steps for :ref:`updating Tails manually `. - -Fore each *Journalist* and *Admin Workstation*, perform the following additional -steps to complete the upgrade: - -1. Boot the USB drive -2. On the Tails welcome screen, unlock the persistent volume and configure an - administrator password -3. Open a terminal (**Applications ▸ Utilities ▸ Terminal**) -4. Run the following commands: - -:: - - cd ~/Persistent/securedrop/admin - rm -rf .venv3 - cd .. - ./securedrop-admin setup - -When prompted by Tails to "Install Only Once" or "Install Every Time", click -**Install Every Time** (this is a change from previous versions of Tails). - -.. include:: ../includes/backup-and-update-reminders.txt - - -Getting Support ---------------- - -Should you require further support with your SecureDrop installation, we are -happy to help! - -.. include:: ../includes/getting-support.txt