Ubuntu 20.04 LTS (Focal) Migration Guide

On April 30, 2021, Ubuntu 16.04 LTS (Xenial), the operating system for the SecureDrop servers, will reach End of Life. In order to continue using SecureDrop, instances must migrate to Ubuntu 20.04 LTS (Focal) before April 30, 2021.

Important

For security reasons, the Source Interface will be automatically disabled on SecureDrop servers still running Ubuntu 16.04 after April 30, 2021.

This migration will require on-premises access to the servers, and a complete reinstallation of Ubuntu and SecureDrop. In-place upgrades and remote upgrades via SSH are not currently supported. We recommend that you plan a two day maintenance window to perform and test the migration.

At a high level, the migration process consists of:

  • Taking a backup of the current instance

  • Installing Ubuntu 20.04 LTS and SecureDrop from scratch

  • Applying the backup

Instances that already have v3 onion services enabled and follow our migration guide will be able to preserve their existing Source and Journalist Interface onion URLs.

Note

Coordinate with journalists and sources during this migration. Your instance will be offline while you perform these steps.

Coordinate with the team maintaining your Landing Page. You may wish to publish a notice about a planned maintenance window. Depending on your migration scenario, you may also need to coordinate the publication of your new Source Interface onion URL so that sources can reach you.

Preparation

Before migrating, complete the following steps:

  1. Consider a hardware upgrade

  2. Choose your migration path and plan your maintenance window

  3. Coordinate with journalists to delete old submissions from the server

  4. Check your SecureDrop version (servers)

  5. Check your SecureDrop version (workstations)

  6. Verify SSH access

  7. Download and verify the Ubuntu 20.04 LTS (Focal) installation media

Consider a hardware upgrade

If you are running hardware that is not currently listed in our hardware recommendations, we recommend that you also plan a hardware refresh as part of this migration, particularly if your hardware is reaching end-of-life. This has the following benefits:

  • It ensures that all system components will continue to receive security updates.

  • It reduces the risk of hardware compatibility issues with future releases of SecureDrop.

  • It will allow you to keep your current installation online during much of the two-day maintenance window.

  • If your hardware is due for replacement anyway, combining the OS upgrade and the hardware upgrade will save you time.

If you have a support agreement with Freedom of the Press Foundation, please coordinate your maintenance window with us, so we can ensure that our team can provide support in a timely manner. In any event, please do not hesitate to contact us for assistance.

Check your SecureDrop version (servers)

To check your SecureDrop server version, load the .onion address of your Source Interface in Tor Browser. The version number will be in the footer. It should currently be 1.8.2.

If you have SSH access to the servers, you can also check the application version from your Admin Workstation by running this command in a terminal:

ssh app apt-cache policy securedrop-app-code

SecureDrop servers are updated automatically with the latest release version. If your servers are running an old version, this indicates a major configuration problem, and you may need to reinstall SecureDrop. In that case, please contact us for assistance.

Check your SecureDrop version (workstations)

  1. (Recommended) Back up your Admin Workstation using the process described here: Back up the Workstations.

  2. Boot your Admin Workstation and wait for the Tails welcome screen to appear.

  3. Unlock the persistent volume and configure an administrator password, then start Tails.

  4. Connect to the Internet and follow all graphical prompts to complete pending updates.

  5. Compare the version shown on the About screen (Applications ▸ Tails ▸ About Tails) with the version indicated on the Tails website. If the installed Tails version is outdated, follow our guide to updating Tails USBs.

    Important

    If your version of Tails is 4.14 or older, you will need to follow these steps to correct an issue with automatic updates.

  6. Run the command git status in the ~/Persistent/securedrop directory. The output should include the following text:

    HEAD detached at <version>
    

    where <version> is the version of the workstation code that is installed. If the Admin Workstation is at 1.8.2, it is up-to-date.

  7. If your SecureDrop code is outdated, follow the latest release guide to perform a manual update. If that fails, please contact us for assistance.

  8. (Recommended) Repeat this process for all Admin Workstations and Journalist Workstations.

Note

If your Admin Workstation is in an unrecoverable state, you can follow our instructions to rebuild an Admin Workstation.

Verify SSH access

Start up your Admin Workstation (with persistent storage unlocked) and run the following commands in a terminal:

ssh app hostname     # command output should be 'app'
ssh mon hostname     # command output should be 'mon'

If you are having trouble accessing the servers via SSH, try the following:

  • create a new Tor network circuit by disconnecting and reconnecting your Internet link, and repeat the check

  • run the ./securedrop-admin tailsconfig command and repeat the check

  • verify that the Source and Journalist Interfaces are available via their desktop shortcuts

  • verify that the Application and Monitor Servers are up

  • contact us for assistance.

Choose Migration Path

If your instance is already using v3 onion services, choose our Standard Migration Procedure.

Instances that have not yet enabled v3 onion services should choose the Alternate Migration Procedure.

Delete Old Submissions from the Server

In coordination with journalists, ensure that any old or unneeded submissions have been deleted from the server. Pruning old submissions will reduce the size and improve the speed of your server backup. Journalists can delete unneeded submissions via the Journalist Interface.

Download and Verify Ubuntu 20.04 LTS (Focal) Installation Media

Follow our instructions to download and verify Ubuntu Server 20.04 LTS and install the .iso file onto a USB stick.

You have now completed all the preparatory steps. The rest of the migration procedure will be completed during your maintenance window.

Migration

Standard Migration Procedure

Perform these steps if your instance is already using v3 onion services. Ensure you have completed the preparatory steps.

  1. Ensure that your Landing Page shows your v3 Source Interface URL. For instances using v2+v3 onion services concurrently, any v2 onion services will be removed as part of this migration.

  2. Announce your maintenance window. As part of this procedure, your servers will become unreachable.

  3. Take a backup of the current instance.

    Once you have taken a backup of the servers, power them off.

    Warning

    The next steps will overwrite existing data on the servers.

    Data from the Monitor Server will not be restored after the backup. If you require historical data from the Monitor Server, archive it separately before proceeding.

    Note

    If you are reusing the same hardware (servers), your old data will be overwritten by the new operating system installation, but traces of this data may still be recoverable.

    In most cases, this is not a concern, since you will be restoring data from your backup file as part of the migration process. However, if this is a concern, refer to our decommissioning documentation for instructions on securely erasing and destroying server data.

  4. Follow the instructions on hardware migration for instances using v2+v3 or v3 onion services. As part of this process, you will be instructed to reinstall your servers, restore your backup, and configure access via your Admin Workstation.

  5. Ensure that all Journalist and Admin Workstations can access the Source and Journalist Interfaces. By this point, for instances that were running v2+v3 onion services concurrently, all v2 onion services will have been disabled. If you have not yet updated the onion service configurations for all Journalist and Admin Workstations, you must do so now.

    Note

    If you cannot update your Journalists’ Tails USBs in person due to remote work policies, contact Support for suggestions on how to safely complete this step.

  6. (Optional): If you’d like your instance to be listed in our SecureDrop directory, ensure your Landing Page meets our security guidelines, and then submit a directory listing request.

    Instances listed in the directory can receive an onion name, an easy-to-type alias for their Source Interface in the form yourinstance.securedrop.tor.onion.

Alternate Migration Procedure

Perform these steps if your SecureDrop instance is not yet using v3 onion services. Ensure you have completed the preparatory steps.

  1. Announce your maintenance window. As part of this procedure, your servers will become unreachable.

  2. Take a backup of the current instance. Once you have taken a backup of the servers, power them off.

    Warning

    The next steps will overwrite existing data on the servers.

    Data from the Monitor Server will not be restored after the backup. If you require historical data from the Monitor Server, archive it separately before proceeding.

    Note

    If you are reusing the same hardware (servers), your old data will be overwritten by the new operating system installation, but traces of this data may still be recoverable.

    In most cases, this is not a concern, since you will be restoring data from your backup file as part of the migration process. However, if this is a concern, refer to our decommissioning documentation for instructions on securely erasing and destroying server data.

  3. Follow our documentation on hardware migration using a v2-only backup.

    As part of this process, you will be instructed to reinstall your servers, generating new v3 onion URLs, and restore source and journalist data from your backup.

  4. Publish your new Source Interface URL on your Landing Page. This is the new, 56-character .onion address at which sources will now reach you.

  5. You will then need to update Journalist and Admin Workstation USBs so that Journalists and other Admins can access your instance.

  6. (Optional): If you’d like your instance to be listed in our SecureDrop directory, ensure your Landing Page meets our security guidelines, and then submit a directory listing request.

    Instances listed in the directory can receive an onion name, an easy-to-type alias for their Source Interface in the form yourinstance.securedrop.tor.onion.

Contact us

If you have questions or comments regarding the pgrade to Ubuntu 20.04 LTS or the preparatory procedure outlined above, please don’t hesitate to reach out: