The Tor Project runs a public Debian package repository intended for the distribution of Tor experimental packages built from CI pipelines in project tpo/core/tor/debian.

The URL for this service is https://deb.torproject.org

• Tutorial
  • How do I use packages from this repository?
• How-to
  • Adding one's PGP key to the keyring allowing uploads
  • Setting up your local clone
  • New tor package release
  • List all packages
  • Remove a package
  • Add a new suite
  • Add a new architecture
  • Drop a suite
• Reference
  • Design
    • Branches and their meanings
  • Maintainer, users, and upstream
  • Packages
    • deb.torproject.org-keyring
    • tor
• Discussion
  • Other alternatives

Tutorial

How do I use packages from this repository?

See the tutorial instructions over at: https://support.torproject.org/apt/tor-deb-repo/

How-to

Adding one's PGP key to the keyring allowing uploads

Package releases will only be allowed for users with a pgp public key, in their gitlab account, that is contained in the TOR_DEBIAN_RELEASE_KEYRING_DEBIAN CI/CD file variable in the tpo/core/debian/tor project.

First, for all operations below, you'll need to be project maintainer in order to read and modify the CI/CD variable. Make sure you are listed as a maintainer in https://gitlab.torproject.org/groups/tpo/core/debian/-/group_members (note that the tpo/core/debian/tor project will inherit the members from there)

To list who's keys are currently present in the keyring:

1. Go to the variables page of the project
2. copy the value of the variable from gitlab's web interface and save this to a file
3. Now list the keys: sq keyring list thisfile.asc
   • or with gpg: gpg thisfile.asc

You'll need to add your key only once as long as you're still using the same key, and it isn't expired. To add your key to the keyring:

1. Go to the variables page of the project
2. copy the value of the variable from gitlab's web interface and save this to a file
3. import public keys from that file, with gpg --import thatfile.asc if you're missing some of them
4. produce a new file by exporting each of them again plus your own key: gpg --export --armor $key1 $key2 $yourkey > newfile.asc
5. copy the contents of the new file and set that as the new value for the CI/CD variable

Setting up your local clone

These things are only needed once, when setting up:

1. Make sure you have sufficient access
2. Clone https://gitlab.torproject.org/tpo/core/debian/tor.git
3. Add the "upstream" tor repository as a remote (https://gitlab.torproject.org/tpo/core/tor.git)
4. Track the debian-* branch for the version you need to release a package for: git switch debian-0.4.8
5. Find the commit hash where the previous version was included: search for "New upstream version:" in the commit history. Then, create a debian-merge-* branch from the last upstream merge commit parent, eg. git branch debian-merge-0.4.8 ca1a6573b7df80f40da29a1713c15c4192a8d8f0
6. Add a tor-pristine-upstream remote and fetch it: git remote add tor-pristine-upstream https://gitlab.torproject.org/tpo/core/debian/tor-pristine-upstream.git
7. Create a pristine-tar branch on the repository: git co -b pristine-tar tor-pristine-upstream/master
8. Create a pristine-tar-signatures branch on the repository: git co -b pristine-tar-signatures tor-pristine-upstream/pristine-tar-signatures
9. Configure git (locally to this repository) for easier pushes. The pristine-tar branch we've created locally differs in name to the remote branch named master. We want to tell git to push to the different name, the one tracked as upstream branch: git config set push.default upstream

New tor package release

If you didn't just follow setting up your local clone you'll need to get your local clone up to date:

1. git remote update
2. switch to pristine-tar and fast-forward to the remote upstream branch
3. switch to pristine-tar-signatures and fast-forward to the remote upstream branch
4. switch to the current minor version branch, e.g. debian-0.4.8, and fast-forward to the remote upstream branch
5. switch to your local debian-merge-0.4.8 branch. Find the commit hash where the previous version was included: search for "New upstream version:" in the commit history. If it's in a different place than your branch, move your branch to it: git reset --hard 85e3ba4bb3

To make the new deb package release:

1. Switch to the debian-merge-0.4.8 branch
2. Verify the latest release tag's signature with git verify-tag tor-0.4.8.15
3. Extract the commit list with git log --pretty=oneline tor-0.4.8.14...tor-0.4.8.15
4. Merge the upstream tag with git merge tor-0.4.8.15
   • Include the upstream commit list in the merge commit message
5. Create a new debian/changelog entry with dch --newversion 0.4.8.15-1 && dch -r and commit with commit message that lets us find where to place debian-merge-0.4.8: git commit -m "New upstream version: 0.4.8.15
6. Switch to the debian-0.4.8 branch and merge debian-merge-0.4.8 into it
7. Create and PGP-sign a new tag on the debian-0.4.8 branch: git tag -s -m'tag debian-tor-0.4.8.15-1' debian-tor-0.4.8.15-1
8. Download the dist tarball including sha256sum and signature
9. Verify the signature and sha256sum of the downloaded tarball
10. Commit the tarball to pristine-tar: pristine-tar commit -v tor-0.4.8.15.tar.gz debian-tor-0.4.8.15-1
11. Switch to the pristine-tar-signatures branch and commit the sha256sum and its detached signature
12. Push pristine-tar and pristine-tar-signature branches upstream
    • git push tor-pristine-upstream pristine-tar-signatures
    • git push tor-pristine-upstream pristine-tar:master the strange syntax is needed here since the local branch is not named the same as the remote one.
13. Switch back to the debian-0.4.8 branch, then push using git push --follow-tags and wait for the CI pipeline run -- specifically, you want to watch the CI run for the commit that was tagged with the debian package version.
14. Promote the packages uploaded to proposed-updates/<suite> to <suite> in reprepro:
    • Test with: for i in $(list-suites | grep proposed-updates | grep -v tor-experimental); do echo " " reprepro -b /srv/deb.torproject.org/reprepro copysrc ${i#proposed-updates/} $i tor; done
    • If it looks good, remove echo " " to actually run it
15. Run static-update-component deb.torproject.org to update the mirrors

List all packages

The show-all-packages command will list packages hosted in the repository, including information about the provided architectures:

tordeb@palmeri:/srv/deb.torproject.org$ bin/show-all-packages

Remove a package

tordeb@palmeri:/srv/deb.torproject.org$ bin/show-all-packages | grep $PACKAGETOREMOVE
tordeb@palmeri:/srv/deb.torproject.org$ reprepro -b /srv/deb.torproject.org/reprepro remove $RELEVANTSUITE $PACKCAGETOREMOVE

Packages are probably in more than one suite. Run show-all-packages again at the end to make sure you got them all.

Add a new suite

In the example below, modifications are pushed to the debian-main branch, from which the latest nightly builds are made. The same modifications must be pushed to all the maintenance branches for releases which are currently supported, such as debian-0.4.8.

Commands run on palmeri must be executed as the tordeb user.

1. Make sure you have sufficient access
2. On the debian-main branch, enable building a source package for the suite in debian/misc/build-tor-sources and debian/misc/backport
3. If the new suite is a debian stable release, update the # BPO section in debian/misc/build-tor-sources.
4. On the debian-ci branch, add the binary build job for the new suite in the job matrix in debian/.debian-ci.yml
5. On palmeri, cd to /srv/deb.torproject.org/reprepro/conf, add the suite in the gen-suites script and run it
6. Merge the debian-ci branch into debian-main and also merge debian-ci into the latest per-version branch (e.g. debian-0.4.8), then push the changes to the git repository (in the tpo/core/debian/tor project) and let the CI pipeline run.
7. From this point, nightlies will be built and uploaded to the new suite, but the latest stable release and keyring packages are still missing.
8. On palmeri:
   1. Copy the packages from the previous suite:
      • reprepro -b /srv/deb.torproject.org/reprepro copysrc <target-suite> <source-suite> deb.torproject.org-keyring
      • reprepro -b /srv/deb.torproject.org/reprepro copysrc <target-suite> <source-suite> tor
   2. Run show-all-packages to ensure the new package was added in the new suite.
   3. Run static-update-component deb.torproject.org to update the mirrors.

Add a new architecture

1. Add the architecture in the job matrix in debian/.debian-ci.yml (debian-ci branch)
2. Add the architecture in /srv/deb.torproject.org/reprepro/conf/gen-suites and run the script
3. Ensure your PGP key is present in the project's TOR_DEBIAN_RELEASE_KEYRING_DEBIAN CI/CD file variable
4. Merge the debian-ci branch and run a CI pipeline in the tpo/core/debian/tor project
5. Run show-all-packages on palmeri to ensure the new package was added in proposed-updates
6. "Flood" the suites in reprepro to populate arch-all packages
   • Test with: for i in $(list-suites | grep -Po "proposed-updates/\K.*" | grep -v tor-experimental); do echo " " reprepro -b /srv/deb.torproject.org/reprepro flood $i; done
   • If it looks good, remove echo " " to actually run it
7. Run static-update-component deb.torproject.org to update the mirrors

Drop a suite

In the example below, modifications are pushed to the debian-main branch, from which the latest nightly builds are made. The same modifications must be pushed to all the maintenance branches for releases which are currently supported, such as debian-0.4.8.

Commands run on palmeri must be executed as the tordeb user.

1. On the debian-main branch, disable building a source package for the suite in debian/misc/build-tor-sources and debian/misc/backport
2. If the new suite is a debian stable release, update the # BPO section in
3. On the debian-ci branch, add the binary build job for the new suite in the job matrix in debian/.debian-ci.yml and push
4. Merge the debian-ci branch into debian-main and also merge debian-ci into the latest per-version branch (e.g. debian-0.4.8) and push
5. On palmeri:
   1. cd to /srv/deb.torproject.org/reprepro/conf, drop the suite from the gen-suites script and run it
   2. Run reprepro -b /srv/deb.torproject.org/reprepro --delete clearvanished to cleanup the archive
   3. Run static-update-component deb.torproject.org to update the mirrors.

Reference

• Host: palmeri.torproject.org
• All the stuff: /srv/deb.torproject.org
• LDAP group: tordeb

The repository is managed using reprepro.

The primary purpose of this repository is to provide a repository with experimental and nightly tor packages. Additionally, it provides up-to-date backports for Debian and Ubuntu suites.

Some backports have been maintained here for other packages, though it is preferred that this happens in Debian proper. Packages that are not at least available in Debian testing will not be considered for inclusion in this repository.

Design

Branches and their meanings

The tpo/core/debian/tor repository uses many branches with slightly different meanings/usage. Here' what the branches are used for:

• debian-ci: contains only changes to the CI configuration file. Changes to CI are then merged into per-version branches as needed.
• debian-main: packaging for the nightly series
• debian-0.x.y: packaging for all versions that start with 0.x.y. For example, the package 0.4.8.15 is expected to be prepared in the branch debian-0.4.8.
• debian-lenny* and debian-squeeze*: legacy, we shouldn't use those branches anymore.

Maintainer, users, and upstream

Packages

The following packages are available in the repository:

deb.torproject.org-keyring

• Maintainer: weasel
• Suites: all regular non-experimental suites

It contains the archive signing key.

tor

• Maintainer: weasel
• Suites: all regular suites, including experimental suites

Builds two binary packages: tor and tor-geoipdb.

Discussion

Other alternatives

You do not need to use deb.torproject.org to be able to make Debian packages available for installation using apt! You could instead host a Debian repository in your people.torproject.org webspace, or alongside releases at dist.torproject.org.