Upgrade from 0.3pre to 0.3.x

SecureDrop 0.3pre was based on the same version of Ubuntu as SecureDrop 0.3.x, so there is no need to do a wipe and clean install of 0.3.x. There is a helper script available to perform the backup and restore.

The upgrade steps in this document will upgrade a 0.3pre SecureDrop to any 0.3.x SecureDrop version. Throughout the rest of this document, substitute 0.3.x with the current release’s version number.

Important Changes

Document Interface Port Change

To make accessing the document interface easier for new users, the Document Interface port for the onion address has been changed from 8080 to 80. This means you will need to update existing Journalists’ bookmarks in their tor browser and remove the :8080 from the end of the onion url.

Prerequisites

  • An Admin networked Tails workstation with persistence enabled and an Admin password set during boot.
  • A filled out prod-specific.yml file

Upgrade Procedure

The upgrade procedure can be performed entirely from the Admin Workstation that you set up when you installed 0.3pre. Start by booting the Admin Tails USB on the Admin Workstation. Make sure you set an Adminstrator Password in the Tails Greeter.

  1. Open a terminal (it is an icon on the top of the screen that looks like a little black TV).

  2. Change into the SecureDrop repo directory

    cd /home/amnesia/Persistent/securedrop
    
  3. Stash your local changes to the inventory and prod-specific.yml

    git stash save "site specific configs"
    
  4. Pull the latest code

    git pull
    
  5. Verify the signed git tag for the latest stable release

    git tag -v 0.3.x
    
  6. Checkout the latest release

    git checkout 0.3.x
    
  7. Pop the site specific configs back in place

    git stash pop
    
  8. Run the 0.3 upgrade helper script. This script will do some basic sanity checks for your ansible inventory, prod-specific.yml and the system’s torrc file are properly configured and then run the correct ansible playbooks.

    ./migration_scripts/0.3pre/upgrade.sh
    

Note on the Ansible “backup” Role

The backup role will not run automatically. This is because unintentionally running the backup role can cause large file transfers over Tor, causing substantial problems during upgrade. If you wish to run a backup manually prior to running the upgrade script, use these commands:

sudo apt-get install ansible
cd /home/amnesia/Persistent/securedrop/install_files/ansible-base
ansible-playbook -i inventory -u $SSH_USER --sudo securedrop-prod.yml --tags backup

Note

Don’t forget to replace $SSH_USER in the command above with the admin username on the app and monitor servers.

Note

If you encounter connection timeouts during the backup, make sure to remove unnecessary submissions from the Document Interface, then run the command again. If you still have problems, contact us at securedrop@freedom.press.

Troubleshooting the 0.3pre upgrade script

If you get an error from the upgrade script, see the list of potential errors and their resolutions below.

  • Error: This script must be run as root.

    Use the ‘sudo’ command and provide the administrative password you created at the beginning of the Tails session.

  • Error: This script must be run on Tails with a persistent volume.

    In order for this to work, you must be running Tails on the admin workstation and have access to a persistent volume. Did you unlock your persistent storage at the beginning of the Tails session?

  • Error: There is no SSH key file present.

    When you installed SecureDrop, you generated an SSH key (and probably saved to the default location: ~/.ssh/id_rsa) for the user ‘amnesia’ and copied it to both the App and Mon server. You should still have access to that key through the OpenSSH persistence in Tails. If you got this error, check if you lost the key or saved it to a different location. You won’t be able to login to the servers remotely without it.

  • Error: This script must be run with SecureDrop's git repository cloned to 'securedrop' in your Persistent folder.

    When you first installed SecureDrop, we assume that you cloned our GitHub repository to a specific location: /home/amnesia/Persistent/securedrop. If it’s not there, you either need to move it there or start anew.

  • Error: There are no HidServAuth values in your torrc file.

    Did you run the ‘SecureDrop Init’ script located in the Persistent folder? The init script and the additions it makes to Tor’s configuration file are needed in order to access the App and Mon servers using SSH over Tor.

  • Error: monitor_ip or app_ip in prod-specific.yml is not an IP address.

    The production playbook in /install_files/ansible-base/prod-specific.yml needs to be fully filled out, with the local IP address for each server specified.

  • Error: ssh_users is not defined in prod-specific.yml.

    Inside the production playbook, you must have ssh_users defined as the name of the user which you use to log in to the App and Mon servers. This is the non-root user account you created when you installed Ubuntu Server.

  • Error: the app or mon ansible_ssh_host in Ansible's inventory file is not an .onion address.

    Our new provisioner, Ansible, must be run over Tor in order to reach the servers. Replace the IP addresses in /install_files/ansible-base/inventory with the .onion hostnames for the App and Mon server’s Tor hidden services for SSH.

  • Error: can't connect to the Application or Monitor Server via SSH.

    Something’s wrong and we can’t connect. You can re-run the script to try again.

    • Is the Vidalia connection indicator green?
    • Did you enter the .onion addresses correctly?
    • Are both servers powered on?
    • Try to SSH to the servers manually - did your client accept the server’s host key?
    • Did the server accept your client’s key?