A wireframe globe breaking out of chains

Free the internet

Support tools that break the chains of censorship and surveillance. Donate to the Tor Project today.

Through December 31, your gift will be matched, up to $250,000!

Donate now

tor

This document is about how we upgrade packages built from the tor source package.

  1. tor
  2. Background
  3. Process
    1. Tip: pushing back expiration date

Background

We build Tails using snapshots of APT repositories. This document assumes a good understanding of this somewhat complex system.

We generally install packages built from the tor source package from http://deb.torproject.org/torproject.org:

The corresponding archive in our APT snapshots setup is called torproject: config/APT snapshots.d/torproject/serial.

Process

The Tails Team member wearing the Front Desk hat creates a tracking issue whenever a new stable version of tor is released.

Once this new version is available in our APT snapshots, a Tails Team member (you!) gathers the data that will inform our decision, and prepares the upgrade:

  1. Fork a branch off stable called NNNNN-tor-X.Y-force-all-tests.

  2. OLD_SERIAL="$(cat config/APT_snapshots.d/torproject/serial)"

  3. On that branch, bump config/APT_snapshots.d/torproject/serial to a snapshot that's recent enough to include the relevant new version of tor:

    auto/scripts/apt-snapshots-serials get-latest torproject \
| cut -d' ' -f2 \
> config/APT_snapshots.d/torproject/serial

  4. Bump the expiration date for the snapshot of the torproject archive that you've switched the branch to. Set the same expiration date as the one for the snapshot of the torproject archive that you've switched the branch from. See tip below.

  5. Push this new branch to our CI.

  6. Compare the Jenkins build and test results to the ones for our stable branch. What follows assumes that these CI results look good. If they don't, more work is needed.

  7. Submit your branch for review via our usual process.

Tip: pushing back expiration date

Let's set some variables: the Debian base distribution, and the old serial (before the change to config/APT_snapshots.d/torproject/serial):

DIST=trixie
OLD_SERIAL=2020020402

Get the timestamp from the Valid-Until field in the Release file for the old snapshot of that distribution, and compute the number of days between now and then:

old_url="https://time-based.snapshots.deb.tails.boum.org/torproject/dists/${DIST:?}/snapshots/${OLD_SERIAL:?}/Release"
old_ts=$(date -d "$(wget -q $old_url -O- | awk '/^Valid-Until:/ {$1=""; print}')" +%s)
now_ts=$(date +%s)
echo "DAYS_FROM_NOW=$(((old_ts-now_ts)/(24*60*60)+1))"