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

  1. Background
  2. 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 https://deb.torproject.org/torproject.org:

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

Process

A Foundations Team member or Release Manager creates a tracking issue whenever a new stable version of tor is released.

Once this new version is available in our APT snapshots, a Foundations 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=bookworm
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))"