From 4506d03b073190ac706e4540d5b5119af4c83d09 Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Thu, 22 Jun 2023 18:27:53 -0400 Subject: [PATCH] Add upgrade guide for 2.6.0 (#468) * Add upgrade guide for 2.6.0 * Remove outdated upgrade guides and include pyproject.toml in update_version script. * Add a reference to the Tail 5.14 security advisory in the 2.6.0 upgrade guide. * Update docs/upgrade/2.5.2_to_2.6.0.rst Co-authored-by: Kunal Mehta --------- Co-authored-by: Nathan Dyer Co-authored-by: Kunal Mehta --- .../admin/installation/set_up_admin_tails.rst | 6 +- docs/admin/maintenance/backup_and_restore.rst | 12 +- docs/conf.py | 2 +- docs/index.rst | 3 +- docs/upgrade/2.3.1_to_2.3.2.rst | 119 ------------------ docs/upgrade/2.5.1_to_2.5.2.rst | 2 - ...{2.3.2_to_2.4.0.rst => 2.5.2_to_2.6.0.rst} | 75 ++++++----- pyproject.toml | 2 +- update_version.sh | 5 +- 9 files changed, 51 insertions(+), 175 deletions(-) delete mode 100644 docs/upgrade/2.3.1_to_2.3.2.rst rename docs/upgrade/{2.3.2_to_2.4.0.rst => 2.5.2_to_2.6.0.rst} (73%) diff --git a/docs/admin/installation/set_up_admin_tails.rst b/docs/admin/installation/set_up_admin_tails.rst index 267e5ebc6..a78aec260 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.5.2 + git tag -v 2.6.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.5.2 + git checkout 2.6.0 -.. important:: If you see the warning ``refname '2.5.2' is ambiguous`` in the +.. important:: If you 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 `__). diff --git a/docs/admin/maintenance/backup_and_restore.rst b/docs/admin/maintenance/backup_and_restore.rst index a4b9c3daf..a1c146f85 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.5.2 + git tag -v 2.6.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.5.2 + git checkout 2.6.0 .. important:: - If you see the warning ``refname '2.5.2' is ambiguous`` in the + If you 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 `__). @@ -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.5.2 + git tag -v 2.6.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.5.2 + git checkout 2.6.0 .. important:: - If you see the warning ``refname '2.5.2' is ambiguous`` in the + If you 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 `__). diff --git a/docs/conf.py b/docs/conf.py index 666b37f09..88b481d20 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ # built documents. # # The short X.Y version. -version = "2.5.2" +version = "2.6.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 18e1374aa..3f89a8df0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -146,13 +146,12 @@ Get Started :maxdepth: 2 :hidden: + upgrade/2.5.2_to_2.6.0.rst upgrade/2.5.1_to_2.5.2.rst upgrade/2.5.0_to_2.5.1.rst upgrade/2.4.2_to_2.5.0.rst upgrade/2.4.1_to_2.4.2.rst upgrade/2.4.0_to_2.4.1.rst - upgrade/2.3.2_to_2.4.0.rst - upgrade/2.3.1_to_2.3.2.rst Get Involved ^^^^^^^^^^^^ diff --git a/docs/upgrade/2.3.1_to_2.3.2.rst b/docs/upgrade/2.3.1_to_2.3.2.rst deleted file mode 100644 index 6c91c67e2..000000000 --- a/docs/upgrade/2.3.1_to_2.3.2.rst +++ /dev/null @@ -1,119 +0,0 @@ -Upgrade from 2.3.1 to 2.3.2 -=========================== - -Update Servers to SecureDrop 2.3.2 ----------------------------------- -Your servers will be updated to the latest version of SecureDrop automatically -within 24 hours of the release. - -Update Workstations to SecureDrop 2.3.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.3.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.3.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.3.2 - -.. important:: If you do see the warning "refname '2.3.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 - -Upgrade to Tails 5.0 --------------------- - -.. important:: - - You must upgrade your workstations to SecureDrop 2.3.2 by following the steps - above *before* upgrading to Tails 5.0. You can verify the version of SecureDrop - by running ``git status`` in your ``~/Persistent/securedrop`` directory. The - output should include "HEAD detached at 2.3.2". - -Tails 5.0 is the first version of Tails to be 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.0 manually. You need a blank USB drive -that you can install Tails 5.0 USB 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). - -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.1_to_2.5.2.rst b/docs/upgrade/2.5.1_to_2.5.2.rst index c7e15664a..5b58c1b94 100644 --- a/docs/upgrade/2.5.1_to_2.5.2.rst +++ b/docs/upgrade/2.5.1_to_2.5.2.rst @@ -1,5 +1,3 @@ -.. _latest_upgrade_guide: - Upgrade from 2.5.1 to 2.5.2 =========================== diff --git a/docs/upgrade/2.3.2_to_2.4.0.rst b/docs/upgrade/2.5.2_to_2.6.0.rst similarity index 73% rename from docs/upgrade/2.3.2_to_2.4.0.rst rename to docs/upgrade/2.5.2_to_2.6.0.rst index f283089b0..460fc27e5 100644 --- a/docs/upgrade/2.3.2_to_2.4.0.rst +++ b/docs/upgrade/2.5.2_to_2.6.0.rst @@ -1,28 +1,46 @@ -Upgrade from 2.3.2 to 2.4.0 +.. _latest_upgrade_guide: + +Upgrade from 2.5.2 to 2.6.0 =========================== -Update Servers to SecureDrop 2.4.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.4.0 +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 `_. -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.4.0 by clicking "Update Now": +Perform the update to 2.6.0 by clicking "Update Now": .. image:: ../images/securedrop-updater.png @@ -42,7 +60,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.4.0 + git tag -v 2.6.0 The output should include the following two lines: :: @@ -55,9 +73,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.4.0 + git checkout 2.6.0 -.. important:: If you do see the warning "refname '2.4.0' is ambiguous" in the +.. 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 `__). @@ -66,29 +84,23 @@ Finally, run the following commands: :: ./securedrop-admin setup ./securedrop-admin tailsconfig -Tor Browser security issue --------------------------- - -Tails has `published an advisory `__ -for a serious security issue in Tor Browser affecting all versions of Tails. Administrators -and journalists should disable JavaScript by `setting Tor Browser’s security level to “Safest” -`__ -until a fix is available (expected on May 31, 2022). If you are using Tor Browser in Tails -for non-SecureDrop browsing, we recommend restarting Tor Browser before and after using it -for SecureDrop. - -Upgrade from Tails 4 to Tails 5 -------------------------------- +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.4.0". + 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 @@ -124,24 +136,9 @@ steps to complete the upgrade: 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). -Language support changes ------------------------- - -We are pleased to announce support for Portuguese (Portugal). To enable this language, -on the *Admin Workstation* run: :: - - ./securedrop-admin sdconfig - -When prompted, add ``pt_PT`` to the list of locales. Then run: :: - - ./securedrop-admin install - -We are currently lacking translators for Hindi and Romanian, which are both at risk -of being removed in the next SecureDrop release. If you speak either language or know -someone who does, please see our instructions on `contributing translations `_. - .. include:: ../includes/backup-and-update-reminders.txt + Getting Support --------------- diff --git a/pyproject.toml b/pyproject.toml index 06a7272b4..b1e063c58 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "securedrop-docs" -version = "2.5.2" +version = "2.6.0" description = "SecureDrop documentation for journalists, sources and administrators" authors = ["SecureDrop team "] readme = "README.md" diff --git a/update_version.sh b/update_version.sh index 4bbb99190..dea95c782 100755 --- a/update_version.sh +++ b/update_version.sh @@ -11,9 +11,10 @@ if [ -z "$NEW_VERSION" ]; then fi readonly OLD_VERSION=$(grep -oP '(?<=^version \= ")\d+\.\d+\.\d+' docs/conf.py) -sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/set_up_admin_tails.rst -sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/backup_and_restore.rst +sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/admin/installation/set_up_admin_tails.rst +sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/admin/maintenance/backup_and_restore.rst sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" docs/conf.py +sed -i "s@$(echo "${OLD_VERSION}" | sed 's/\./\\./g')@$NEW_VERSION@g" pyproject.toml echo "Versions updated. Verify the results with 'git diff' and be sure to tag" echo "a new stable version as part of the release process."