Tor integration in Whonix ™ Development Notes

From Whonix

< Dev

Tor Version[edit]

According to the Tor release note [archive], there are usually several different major versions of Tor supported by the Tor project. However, due to the the limited time the Tor packager has, only a few major versions are packaged and ready to be used.

For example, in December, 2017, five major versions of Tor were supported. Specifically:

  1. Debian stretch repository contained another LTS, which was version 0.2.9.
  2., also known as Tor, Tor Project or TPO repository, had the latest stable Tor which was version

A major consideration in choosing the most suitable Tor version for Whonix ™ is that the latest stable found in the TPO repository may lead to network breakage. [1] The reason is the "stable" tag indicates it is stable version of Tor, which does not necessarily match the "stable" Debian version that Whonix ™ is actually using. [2]

There are three primary Tor options for Whonix ™ developers and each of them has pros and cons:

1. Use the Tor LTS version from the official Debian package repository:

  • Advantages: Minimal effort is required in Whonix ™.
  • Disadvantages: Misses the advantages of later versions (see below).

2. Use latest stable in TPO repository and allow testers to use the Tor nightly build in Whonix ™, with bug reporting bug to TPO

  • Advantages: Latest features, better security, improved Tor Browser compatibility (using SocksPort with flags and even better connectivity performance). [3]
  • Disadvantages:
    • From the Whonix ™ perspective, these packages are uploaded to at random times. These packages are not guaranteed to be compatible with Whonix ™. While there are no security concerns, these packages could break a system's apt-get package management (due to incompatible dependencies) or connectivity, in case Tor refuses to start. This can arise due to a configuration incompatibility in a newer version of Tor, or for other reasons such as systemd or apparmor related changes.
    • In May 2021 a transient repository issue [archive] broke [archive] Whonix ™ build process.
    • There is nothing similar to Keeps changing (newer versions being added). Hence, can introduce build issues such as above. Unsuitable for reproducible builds / Verifiable Builds.
    • Porting to other architectures issues.
      • Only available for the i386, amd64, arm64 architectures.
      • Introduces differences / issues such as for example for the ppc64el platform. [4]

3. Versions are downloaded from, verified to work, and then migrated to

  • Advantages: Flexibility in version selection, a guaranteed way to confirm that only stable Tor versions which are functional in Whonix ™ will be uploaded.
  • Disadvantages:
    • A few testers are needed, manual uploads are required, and Whonix ™ touches Tor.
    • Other issues from 2. above equally apply.

Whonix ™ developers have chosen the third method for now. [5] However, the comparison above suggests better security and compatibility is afforded by the second option. This approach requires a lot of active testers who can use the Tor nightly build and report bugs to the Tor project or Whonix ™. [6]

Tor Config Files[edit]

Rationale for Tor Drop-In Configuration Folder[edit]

Having a Tor Configuration Drop-In Folder makes implementation of additional features that require additional Tor settings much easier. For example it could improve usability to provide a whonix-gw-hidden-webserver package, that automates the Whonix-Gateway ™ specific instructions for Onion Services. Such a package could just drop the configuration snippet there, and if the feature gets disabled or the package installed, that configuration snippet gets purged. Adding additions to /etc/tor/torrc with a script is problematic, because those additions cannot be removed by a script if the user slightly modified those lines and because these can cause a dpkg interactive conflict resolution dialog.

Current Implementation[edit]

The implementation is as it follows.

Rejected Alternatives[edit]

Only Two Config Files[edit]

  • Using only /usr/share/tor/tor-service-defaults-torrc and /etc/tor/torrc, not using /etc/tor/torrc.examples.
  • And having configuration examples (instructions) in /usr/share/tor/tor-service-defaults-torrc. Using a minimal /etc/tor/torrc to tell them to look into /usr/share/tor/tor-service-defaults-torrc for configuration examples.
  • This is a bad idea, because users get tempted comment in things in /usr/share/tor/tor-service-defaults-torrc.
  • When they do this, they settings would get lost and overwritten without asking next time they update anon-gw-anonymizer-config [archive], because /usr/share/tor/tor-service-defaults-torrc is not a configuration file (since in /usr, not /etc folder).

Only One Config File[edit]

  • Using only /etc/tor/torrc, leaving /usr/share/tor/tor-service-defaults-torrc with defaults (from Debian), not using /etc/tor/torrc.examples.
  • Using /etc/tor/torrc for user examples, user's own modifications and Whonix ™ Tor settings.
  • This is bad, because when users have edited /etc/tor/torrc and anon-gw-anonymizer-config gets updated, it will throw an dpkg interactive conflict resolution dialog. Users might decide to keep their old config file and will miss (security) improvements.

Tor Control[edit]

See Talking to the real Tor Control Port.

Why Waste Network Bandwidth by Downloading Operating System Updates over Tor?[edit]

The short answer is this option was discussed with The Tor Project and Whonix ™ was granted permission to do so.

Interested readers who want to learn more should review the following:

Forum Discussion[edit]


  1. [archive]
  2. The Debian target is usually the stable package, which is currently: bullseye) or Whonix ™.
  3. Patrick: "Historically when there was a botnet starting to use Tor, the LTS version barely connected while the latest stable had the ntor handshake which worked." See [1] [archive].
  4. Package: tor-geoipdb Version: is Architecture: all and Depends: tor (>= Thereby for example ended up in Whonix ™ repository for architecture ppc64el. This did not cause an issue yet.
  5. Relative Whonix ™ Forum discussion: [archive]
  6. Please contact us if you would like to be a Tor nightly build tester for Whonix ™.
  7. Click here [archive] for an overview of all answers.

Fosshost is sponsors Kicksecure ™ stage server Whonix old logo.png
Fosshost About Advertisements

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png Iconfinder Apple Mail 2697658.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Want to help create awesome, up-to-date screenshots for the Whonix ™ wiki? Help is most welcome!

https link onion link Priority Support | Investors | Professional Support

Whonix | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent.