Tor integration in Whonix Development Notes

Whonix ®

Download

Windows Linux Mac VirtualBox KVM Qubes Intel / AMD64 ARM64 PPC64 USB ISO Raspberry Pi More options Source Code

About

Overview Features Whonix vs VPNs Why Open Source? Project Activities Contributors Mission & Vision

Docs

Documentation FAQ Troubleshooting

Community

Forums Forum Best Practices Contribute

Support

Self Support First Policy Search Engines, Docs and AI Support (Limited) Reporting Bugs Contact (Restricted)

Tools Upload file Special pages Recent changes Print Version Page meta What links here Related changes Page information

Page Read Edit History Move Protection Unwatch Watch Delete Purge

User Preferences Watchlist Contributions Logout Create account Login

Donate

• Tor
• Anon Connection Wizard
• tor-control-panel
• Why does Whonix use Tor?
• Tor Entry Guards
• Tor Myths and Misconceptions
• Tor Controller
• tor-ctrl-observer
• onion-grater
• Tor (Developer)
• onion-grater (Developer)
• anon-ws-disable-stacked-tor (Developer)

Tor Version, Package source (Debian, backports, Tor Project package repository), Config Files, Miscellaneous

Tor Version

There are two implementations of Tor.

• C Tor - Originally just called "Tor". This original implementation of Tor written in the C programming language.
• Arti - New rust based implementation of Tor.

Both are developed by its upstream developer, The Tor Project.

According to the Tor release note, 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. deb.torproject.org, also known as Tor, Tor Project or TPO repository, had the latest stable Tor which was version 0.3.1.9.

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. 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.

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: packages.debian.org

• Advantages: Minimal effort is required in Whonix.
• Disadvantages: Might miss the advantages of later versions (see below).
  • While this was true in past, development of C Tor has slowed down because its replacement Arti is now the development focus of the Tor developers.
    • Related: Whonix forum discussion Keep an eye on Arti (Tor)

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).
• Disadvantages:
  • From the Whonix perspective, these packages are uploaded to deb.torproject.org 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 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 broke Whonix build process.
  • In December 2022, caused issue FAILED to start Anonymizing overlay network for TCP - Tor fails to start a few times before succeeding to start.
  • In February 2023, might have caused issue Fresh whonix-kvm install gateway error.
  • In December 2023, Tor 0.4.8.9 broken connectivity in combination with vanguards / vanguards broken with Tor 0.4.8.9 / Connections drop on Tor 0.4.8.9.
  • There is nothing similar to snapshot.debian.org. 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.

3. Versions are downloaded from deb.torproject.org, verified to work, and then migrated to deb.whonix.org

• 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.

4. Version downloaded from Debian backports, verified to work, and then migrated to deb.whonix.org

Advantages:

• • Good other architecture support. No porting to other architectures issues.

Open Questions:

Scenario A)...

1. Newer Tor version downloaded from Debian backports.
2. Verified to work, and then migrated to deb.whonix.org.
3. Debian backports starting to provide an even Tor newer version.
4. TODO: Would it get automatically get installed?

Scenario B)...

1. Newer Tor version downloaded from Debian backports.
2. Verified to work, and then migrated to deb.whonix.org.
3. Debian backports becoming outdated but Tor Project repository providing a newer version.
4. Newer Tor version downloaded from TPO repository.
5. Migrated to deb.whonix.org.
6. TODO: Would the newer Tor version get installed or would the installed Tor version from Debian backports prevent that?

Current Choice

Whonix developers have chosen the third method for Whonix 16. However, the comparison above suggests better security and compatibility is afforded by the second option. This approach however would requires a lot of active testers who can use the Tor nightly build and report bugs to the Tor project or Whonix, which are unavailable.

Whonix developers have chosen the first method for Whonix 17 because development of C Tor has slowed down in favor or Arti as mentioned above.

Back to third method. https://forums.whonix.org/t/tor-integration-in-whonix/10593/45

Tor Config Files

Rationale for Tor Drop-In Configuration Folder

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

The implementation is as it follows.

• /etc/tor/torrc holds minimal content, so ideally it will need as few updates as possible or never again in the future. The only effective command is %include /etc/torrc.d/ which results in parsing folder /etc/torrc.d.
• The lexical high file /etc/torrc.d/95_whonix.conf instructions to %include /usr/local/etc/torrc.d/.
• Instructions in /etc/tor/torrc and documentation instructs users to not edit that file and use use /usr/local/etc/torrc.d/50_user.conf instead.
• /etc/tor/torrc.examples contains configuration examples.
• Some Whonix Tor settings unfortunately still go into /usr/share/tor/tor-service-defaults-torrc due to Qubes-Whonix eth1 static networking feature not being implemented yet.
• Most users probably ignore /usr/share/tor/tor-service-defaults-torrc, because this file is barely advertised and barely popular.
• /usr/share/tor/tor-service-defaults-torrc can be modified by Qubes-Whonix replace-ips without any conflicts with user modifications or dpkg interactive conflict resolution dialog.
  • https://github.com/Whonix/anon-gw-anonymizer-config/blob/master/usr/lib/systemd/system/anon-gw-anonymizer-config.service
• Debian feature request: add torrc.d configuration directory
• Initial Tor feature request: torrc.d-style configuration directories
• Improvement Tor feature request: Parse only .torrc files in torrc.d directory
• https://github.com/Whonix/anon-gw-anonymizer-config

Rejected Alternatives

Only Two Config Files

• 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, because /usr/share/tor/tor-service-defaults-torrc is not a configuration file (since in /usr, not /etc folder).

Only One Config File

• 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

See Talking to the real Tor Control Port.

Tor Readiness to Serve Connections API

What is the API for "When Tor is ready to serve connections?"

The short answer is: none.

Unfortunately there isn't reliable API for that. There is Tor control protocol status/circuit-established which can return 1 (yes) but that doesn't mean a connection will succeed. The only way to test it would be to actually test it such as using curl against some clearnet or onion domain(s). But which ones? Avoiding single points of failure.

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

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:

• Tor Project thread about this issue; see updates over Tor, should not waste Tor bandwidth.
• The Tor Project was asked directly, after this issue and possible solutions were discussed thoroughly by the Whonix team; see tor-talk Operating system updates / software installation behind Tor Transparent Proxy.
• Andrew Lewman, a former Executive Director, Director and press contact for Tor downloads a lot of updates over the network and did not complain.

Forum Discussion

• https://forums.whonix.org/t/tor-integration-in-whonix/10593
• https://forums.whonix.org/t/tor-upgrades/10302

Tor Duplicate Config File Restart Bug

May 27 13:04:26 host systemd[1]: tor.service: Succeeded.
May 27 13:04:26 host systemd[1]: Stopped Anonymizing overlay network for TCP (multi-instance-master).
May 27 13:04:26 host systemd[1]: Stopping Anonymizing overlay network for TCP (multi-instance-master)...
May 27 13:04:26 host systemd[1]: Stopping Anonymizing overlay network for TCP...
May 27 13:04:26 host systemd[1]: tor@default.service: Succeeded.
May 27 13:04:26 host systemd[1]: Stopped Anonymizing overlay network for TCP.
May 27 13:04:26 host systemd[1]: tor@default.service: Consumed 1min 6.810s CPU time.
May 27 13:04:26 host systemd[1]: anon-gw-anonymizer-config.service: Succeeded.
May 27 13:04:26 host systemd[1]: Stopped Make Sure Torrc Files Exist and Clean Tor Config Folders.
May 27 13:04:26 host systemd[1]: Stopping Make Sure Torrc Files Exist and Clean Tor Config Folders...
May 27 13:04:26 host systemd[1]: Starting Make Sure Torrc Files Exist and Clean Tor Config Folders...
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -d /etc/tor ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -d /etc/torrc.d ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -d /usr/local/etc/torrc.d ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -e /etc/tor/torrc ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -e /etc/torrc.d/95_whonix.conf ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -e /usr/local/etc/torrc.d/40_tor_control_panel.conf ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' '!' -e /usr/local/etc/torrc.d/50_user.conf ']'
May 27 13:04:26 host tor-config-sane[17986]: + '[' -n '' ']'
May 27 13:04:26 host tor-config-sane[17986]: + tor_user=debian-tor
May 27 13:04:26 host tor-config-sane[17986]: + '[' -n '' ']'
May 27 13:04:26 host tor-config-sane[17986]: + tor_group=debian-tor
May 27 13:04:26 host tor-config-sane[17986]: + '[' -n '' ']'
May 27 13:04:26 host tor-config-sane[17986]: + tor_dir=/var/lib/tor
May 27 13:04:26 host tor-config-sane[17986]: + '[' -n '' ']'
May 27 13:04:26 host tor-config-sane[17986]: + client_onion_auth_dir=/var/lib/tor/authdir
May 27 13:04:26 host tor-config-sane[17986]: + mkdir -p /var/lib/tor/authdir
May 27 13:04:26 host tor-config-sane[17986]: + chown debian-tor:debian-tor /var/lib/tor/authdir
May 27 13:04:26 host tor-config-sane[17986]: + search='%include /etc/torrc.d/
May 27 13:04:26 host tor-config-sane[17986]: %include /etc/torrc.d/95_whonix.conf'
May 27 13:04:26 host tor-config-sane[17986]: + replace='%include /etc/torrc.d/'
May 27 13:04:26 host tor-config-sane[17986]: + file_name=/etc/tor/torrc
May 27 13:04:26 host tor-config-sane[17986]: + LANG=C
May 27 13:04:26 host tor-config-sane[17986]: + str_replace '%include /etc/torrc.d/
May 27 13:04:26 host tor-config-sane[17986]: %include /etc/torrc.d/95_whonix.conf' '%include /etc/torrc.d/' /etc/tor/torrc
May 27 13:04:26 host tor-config-sane[17989]: Nothing replaced
May 27 13:04:26 host tor-config-sane[17986]: + true 0
May 27 13:04:26 host tor-config-sane[17990]: /usr/libexec/anon-gw-anonymizer-config/torrc-d-cleaner INFO: start.
May 27 13:04:26 host tor-config-sane[17990]: INFO: dpkg-new file found: /etc/torrc.d/60_network.conf.dpkg-new
May 27 13:04:26 host tor-config-sane[17990]: INFO: dpkg-new file found: /etc/torrc.d/65_gateway.conf.dpkg-new
May 27 13:04:26 host tor-config-sane[17990]: INFO: dpkg-new file found: /etc/torrc.d/65_leak_tests.conf.dpkg-new
May 27 13:04:26 host tor-config-sane[17990]: INFO: dpkg-new file found: /etc/torrc.d/70_workstation.conf.dpkg-new
May 27 13:04:26 host tor-config-sane[17990]: INFO: dpkg-new file found: /etc/torrc.d/95_whonix.conf.dpkg-new
May 27 13:04:26 host tor-config-sane[17990]: /usr/libexec/anon-gw-anonymizer-config/torrc-d-cleaner INFO: success.
May 27 13:04:26 host systemd[1]: Finished Make Sure Torrc Files Exist and Clean Tor Config Folders.
May 27 13:04:26 host systemd[1]: Starting Anonymizing overlay network for TCP (multi-instance-master)...
May 27 13:04:26 host systemd[1]: Starting Anonymizing overlay network for TCP...
May 27 13:04:26 host systemd[1]: Finished Anonymizing overlay network for TCP (multi-instance-master).
May 27 13:04:26 host vanguards[762]: WARNING[Fri May 27 13:04:26 2022]: Tor daemon connection closed. Trying again...
May 27 13:04:26 host tor[17993]: May 27 13:04:26.803 [notice] Tor 0.4.7.7 running on Linux with Libevent 2.1.12-stable, OpenSSL 1.1.1n, Zlib 1.2.11, Liblzma 5.2.5, Libzstd 1.4.8 and Glibc 2.31 as libc.
May 27 13:04:26 host tor[17993]: May 27 13:04:26.803 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://support.torproject.org/faq/staying-anonymous/
May 27 13:04:26 host tor[17993]: May 27 13:04:26.806 [notice] Read configuration file "/usr/share/tor/tor-service-defaults-torrc".
May 27 13:04:26 host tor[17993]: May 27 13:04:26.806 [notice] Read configuration file "/etc/tor/torrc".
May 27 13:04:26 host tor[17993]: May 27 13:04:26.807 [notice] Processing configuration path "/etc/torrc.d/" at recursion level 1.
May 27 13:04:26 host tor[17993]: May 27 13:04:26.807 [notice] Including configuration file "/etc/torrc.d//60_network.conf".
May 27 13:04:26 host tor[17993]: May 27 13:04:26.808 [notice] Including configuration file "/etc/torrc.d//60_network.conf.dpkg-new".

Footnotes

Whonix The most watertight privacy operating system in the world.

Dark mode

Follow us on social media

Supported by Power Up Privacy

Whonix is proudly supported until 2025 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint 2012- 2025 ENCRYPTED SUPPORT LLC

Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!