From 2fbe91cb64ec1f93293464ca2b9e1c4ba1c5645b Mon Sep 17 00:00:00 2001 From: Erik Moeller Date: Wed, 12 May 2021 10:57:29 -0700 Subject: [PATCH] Add upgrade guide; remove Tails 3 & prev. version guide; bump version --- docs/backup_and_restore.rst | 12 +-- docs/conf.py | 4 +- docs/index.rst | 3 +- docs/set_up_admin_tails.rst | 6 +- docs/upgrade/1.6.0_to_1.7.0.rst | 138 -------------------------------- docs/upgrade/1.7.0_to_1.7.1.rst | 3 +- docs/upgrade/1.8.1_to_1.8.2.rst | 88 ++++++++++++++++++++ docs/upgrade_to_tails_4.rst | 61 -------------- 8 files changed, 101 insertions(+), 214 deletions(-) delete mode 100644 docs/upgrade/1.6.0_to_1.7.0.rst create mode 100644 docs/upgrade/1.8.1_to_1.8.2.rst delete mode 100644 docs/upgrade_to_tails_4.rst diff --git a/docs/backup_and_restore.rst b/docs/backup_and_restore.rst index 60e946f9f..f7edaf4d8 100644 --- a/docs/backup_and_restore.rst +++ b/docs/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 1.8.1 + git tag -v 1.8.2 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 1.8.1 + git checkout 1.8.2 .. important:: - If you see the warning ``refname '1.8.1' is ambiguous`` in the + If you see the warning ``refname '1.8.2' is ambiguous`` in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). @@ -471,7 +471,7 @@ source accounts, and journalist accounts. To do so, follow the steps below: cd ~/Persistent/securedrop/ git fetch --tags - git tag -v 1.8.1 + git tag -v 1.8.2 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 1.8.1 + git checkout 1.8.2 .. important:: - If you see the warning ``refname '1.8.1' is ambiguous`` in the + If you see the warning ``refname '1.8.2' 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 daa0a0cb7..5a0485bac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,9 +68,9 @@ # built documents. # # The short X.Y version. -version = "1.8.1" +version = "1.8.2" # The full version, including alpha/beta/rc tags. -release = "1.8.1" +release = "1.8.2" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index 5f6534483..580a70efe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,7 +83,6 @@ anonymous sources. getting_support v3_services update_bios - upgrade_to_tails_4 offboarding decommission @@ -93,10 +92,10 @@ anonymous sources. :maxdepth: 2 upgrade/focal_migration.rst + upgrade/1.8.1_to_1.8.2.rst upgrade/1.8.0_to_1.8.1.rst upgrade/1.7.1_to_1.8.0.rst upgrade/1.7.0_to_1.7.1.rst - upgrade/1.6.0_to_1.7.0.rst .. toctree:: :caption: Developer Documentation diff --git a/docs/set_up_admin_tails.rst b/docs/set_up_admin_tails.rst index 98ecb8ca4..6b39df99f 100644 --- a/docs/set_up_admin_tails.rst +++ b/docs/set_up_admin_tails.rst @@ -137,7 +137,7 @@ signed with the release signing key: cd ~/Persistent/securedrop/ git fetch --tags - git tag -v 1.8.1 + git tag -v 1.8.2 The output should include the following two lines: @@ -158,9 +158,9 @@ screen of your workstation. If it does, you can check out the new release: .. code:: sh - git checkout 1.8.1 + git checkout 1.8.2 -.. important:: If you see the warning ``refname '1.8.1' is ambiguous`` in the +.. important:: If you see the warning ``refname '1.8.2' is ambiguous`` in the output, we recommend that you contact us immediately at securedrop@freedom.press (`GPG encrypted `__). diff --git a/docs/upgrade/1.6.0_to_1.7.0.rst b/docs/upgrade/1.6.0_to_1.7.0.rst deleted file mode 100644 index f946e7ed7..000000000 --- a/docs/upgrade/1.6.0_to_1.7.0.rst +++ /dev/null @@ -1,138 +0,0 @@ -Upgrade from 1.6.0 to 1.7.0 -=========================== - -.. important:: - - Please see the :ref:`key reminders ` below regarding critical - migrations of your SecureDrop servers that must be completed before - **April 30, 2021** to keep your instance operational. - -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_170: - -Updating Workstations to SecureDrop 1.7.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.7.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.7.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.7.0 - -.. important:: If you do see the warning "refname '1.7.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. - - -.. include:: ../includes/always-backup.txt - -.. _key_reminders: - -Migration to v3 onion services ------------------------------- - -Support for v2 :ref:`onion services ` is being phased -out and will be completely removed as part of the transition to Ubuntu 20.04. -If you are not already running v3 onion services (easily recognizable by their -56 character ``.onion`` addresses), please complete the migration at your -earliest convenience to keep your instance running. See our -:doc:`upgrade guide <../v3_services>` for details. - -.. note:: - - If you have previously disabled v2 onion services, due to a bug that was fixed - in SecureDrop 1.7.0, SSH access via v2 onion services may still be enabled, - and you may receive OSSEC alerts warning you that v2 onion services are still - running. - - To fully disable v2 onion services: - - 1. Make sure that your *Admin Workstation* is up-to-date by following the - :ref:`earlier steps `. - 2. Run ``./securedrop-admin sdconfig`` from the ``~/Persistent/securedrop`` - directory and confirm that all configuration settings are correct. - In particular, make sure that v2 onion services are disabled, and - v3 onion services are enabled. - 3. Re-run the install playbook via ``./securedrop-admin install``. - - We apologize for the inconvenience. Please contact us if you have any - questions about this process. - -Preparing for Ubuntu 20.04 --------------------------- -The current server operating system, Ubuntu 16.04, will no longer receive -security updates after April 30, 2021. Support for Ubuntu 20.04 is planned -for the SecureDrop 1.8.0 release, scheduled for March 9, 2021. We recommend -that you schedule a two-day maintenance window **between March 9 and April 30**. - -Before then, we encourage you to take :doc:`preparatory steps ` -to ensure that the migration will go smoothly. - -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/1.7.0_to_1.7.1.rst b/docs/upgrade/1.7.0_to_1.7.1.rst index 8a7ac86fc..5db838368 100644 --- a/docs/upgrade/1.7.0_to_1.7.1.rst +++ b/docs/upgrade/1.7.0_to_1.7.1.rst @@ -3,8 +3,7 @@ Upgrade from 1.7.0 to 1.7.1 SecureDrop 1.7.1 is a bugfix release to address an issue introduced in SecureDrop 1.7.0 which caused an outage for some long-running SecureDrop -instances. Please see :doc:`1.6.0_to_1.7.0` for important information about -SecureDrop 1.7.0. +instances. Automatic server upgrades ------------------------- diff --git a/docs/upgrade/1.8.1_to_1.8.2.rst b/docs/upgrade/1.8.1_to_1.8.2.rst new file mode 100644 index 000000000..50d40254b --- /dev/null +++ b/docs/upgrade/1.8.1_to_1.8.2.rst @@ -0,0 +1,88 @@ +Upgrade from 1.8.1 to 1.8.2 +=========================== + +.. important:: + + If you have not migrated your servers to Ubuntu 20.04 yet, you must do so + at the earliest opportunity. Servers running on Ubuntu 16.04 no longer + receive operating system or SecureDrop software updates at this point. + + Please see our :doc:`migration guide ` for instructions + for performing a migration, or :doc:`reinstall SecureDrop <../overview>`. + +Updating Servers to SecureDrop 1.8.2 +------------------------------------ +Servers running Ubuntu 20.04 will be updated to the latest version of SecureDrop +automatically within 24 hours of the release. + +Updating Workstations to SecureDrop 1.8.2 +----------------------------------------- + +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.8.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 \ + "2224 5C81 E3BA EB41 38B3 6061 310F 5612 00F4 AD77" + git tag -v 1.8.2 + +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.8.2 + +.. important:: If you do see the warning "refname '1.8.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 + +Updating Tails +-------------- +Check the version of Tails on your *Admin* and *Journalist Workstations* +(**Applications ▸ Tails ▸ About Tails**). If your workstations are running Tails +version 4.14 or earlier, you will not receive an update notification due to a +bug. Perform a :ref:`manual update `, or reinstate +automatic updates by following the steps in the +`Tails advisory `__. + +If you are running Tails 4.15 or later, follow the graphical prompts to update +to the latest version. + +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 deleted file mode 100644 index ade7e63f9..000000000 --- a/docs/upgrade_to_tails_4.rst +++ /dev/null @@ -1,61 +0,0 @@ -Upgrading workstations from Tails 3 to Tails 4 ----------------------------------------------- - -.. note:: - - This guide will be removed in a future release of this documentation, and - is no longer actively tested as part of SecureDrop QA. If you still use older - Tails USB drives and encounter issues during the upgrade, please get in - touch. - -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 workstations. 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. - -Once the upgrade is completed, shut down the *Tails 4 Primary USB* and boot into -each workstation USB to verify that the upgrades were successful. On the *Secure Viewing Station* USB, the upgrade process is now complete, and no additional configuration is required. - -On the *Admin* and *Journalist Workstation* USBs, set an administrator password on the Tails welcome screen, and update the SecureDrop environment using the -following commands: :: - - cd ~/Persistent/securedrop - ./securedrop-admin update - ./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. - -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. - - -Getting Support ---------------- - -Should you require further support with your SecureDrop installation, we are -happy to help! - -.. include:: ./includes/getting-support.txt