- 1 Configuration Check
- 2 Edit Tor Configuration
- 3 Log Analysis
- 4 Permissions Fix
- 5 Non-Issues
- 6 Version Number
- 7 Advanced Topics
- 7.1 Additional SocksPorts
- 7.2 Blacklist Certain Onion Services from Connecting
- 7.3 Entry Guards
- 7.4 Manual Bridge Configuration
- 7.5 Tor Functions
- 7.6 UDP
- 7.7 ICMP
- 8 FAQ
- 9 Further Reading
- 10 Footnotes / References
To discover if there are any Tor configuration syntax errors and to see which Tor configuration files are processed in which order, run the following command inside Whonix-Gateway ™ (Qubes-Whonix ™:
The output should be similar to the following.
/===================================================================\ | Report Summary | \===================================================================/ No error detected in your Tor configuration. Tor verify exit code: 0 /===================================================================\ | Tor Full Report | \===================================================================/ Aug 09 19:29:56.669 [notice] Tor 0.3.3.9 (git-ca1a436fa8e53a32) running on Linux with Libevent 2.0.21-stable, OpenSSL 1.1.0f, Zlib 1.2.8, Liblzma 5.2.2, and Libzstd 1.1.2. Aug 09 19:29:56.669 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://www.torproject.org/download/download#warning Aug 09 19:29:56.669 [notice] Read configuration file "/usr/share/tor/tor-service-defaults-torrc". Aug 09 19:29:56.669 [notice] Read configuration file "/etc/tor/torrc". Aug 09 19:29:56.672 [notice] You configured a non-loopback address '10.137.8.1:5300' for DNSPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. Aug 09 19:29:56.672 [notice] You configured a non-loopback address '10.137.8.1:9040' for TransPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. Configuration was valid /===================================================================\ | Used Tor Configuration Files | \===================================================================/ 5 files are used as Tor configuration files: /usr/share/tor/tor-service-defaults-torrc /etc/tor/torrc /etc/torrc.d/95_whonix.conf /usr/local/etc/torrc.d/40_tor_control_panel.conf /usr/local/etc/torrc.d/50_user.conf =====================================================================
Edit Tor Configuration
Analysis of Tor's log can be useful if connectivity issues emerge.
Open Tor Log
Users can inspect two logs:
- The persistent Tor log: /var/log/tor/log; and/or
- The Tor log since last boot: /var/run/tor/log 
Open /var/run/tor/log in an editor with root rights.
Watch Tor Log
Users can also watch Tor's log as it is written.
sudo tail -f /var/run/tor/log
This command is especially useful when Tor is reloaded or restarted simultaneously in another terminal window.
To reload Tor, run the following command.
sudo service tor@default reload
To restart Tor, run the following command.
sudo service tor@default restart
If error messages like the following appear.
Oct 24 07:22:15.693 [warn] Directory /var/lib/tor/.tor cannot be read: Permission denied
Oct 25 12:35:07.460 [warn] Directory /var/lib/tor cannot be read: Permission denied
Oct 25 12:35:07.460 [warn] Failed to parse/validate config: Couldn't access private data directory "/var/lib/tor"
Then apply the following steps.
|Message / Question||Answer|
|Am I compromised? Does Tor's log report leaks?||Tor's output is an ineffective tool for discovering serious issues such as a compromise or leaks.|
|[WARN] Socks version 71 not recognized. (Tor is not an http proxy.)||
This warning is caused by whonixcheck, specifically the function check_tor_socks_port_reachability which checks if a Tor SocksPort is reachable by trying to fetch it using curl.  No warnings appear if the function works correctly.
|[warn] Socks version 71 not recognized. (This port is not an HTTP proxy; did you want to use HTTPTunnelPort?)||Similar to above.|
|[NOTICE] You configured a non-loopback address '10.152.152.10:9179' for SocksPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. [1 duplicate hidden] This notice may reference other port numbers, or the DnsPort or TransPort.||This notice is not a concern because Tor really listens on that IP/port - it is the internal network interface for Whonix-Gateway ™ (|
|[NOTICE] New control connection opened. [2 duplicates hidden] A higher number of duplicate messages may also appear.||This notice is not a concern because it is caused by whonixcheck's Tor Bootstrap Status Test, which uses Tor's ControlPort or CPFP.|
To discover what Tor version is currently in use, run the following command inside Whonix-Gateway ™ (Qubes-Whonix ™:
The output should be similar to the following.
INFO: version of the 'tor' package: 0.3.5.8-1~d90.stretch+1
Adding additional Tor SocksPorts to /usr/local/etc/torrc.d/50_user.conf is non-intuitive. 
As noted in the Tor man page (
By default, an option on the command line overrides an option found in the configuration file, and an option in a configuration file overrides one in the defaults file.
This rule is simple for options that take a single value, but it can become complicated for options that are allowed to occur more than once: if you specify four SOCKSPorts in your configuration file, and one more SOCKSPort on the command line, the option on the command line will replace all of the SOCKSPorts in the configuration file. If this is not what you want, prefix the option name with a plus sign, and it will be appended to the previous set of options instead.
Nick Mathewson from The Tor Project has also noted: 
So to make sure that the SocksPort in the torrc does what you want, write it as
After adding custom ports, a user would also have to edit the Whonix ™ firewall unless they were lucky. For example, various custom ports for such use cases have already been added. Those are documented here.
Blacklist Certain Onion Services from Connecting
The following is an example onion service that is added to /usr/local/etc/torrc.d/50_user.conf. Replace bbbbbb6qtmqg65g6.onion with the actual onion service that should be blacklisted.
MapAddress bbbbbb6qtmqg65g6.onion 127.0.0.1
This entry has been moved here.
Manual Bridge Configuration
It is recommended to first read the main Bridges article.
For the majority of users, the Anon Connection Wizard GUI application is suitable for bridge configuration. The manual bridge configuration steps below are only recommended for advanced users.
Step 1: Access Tor Configuration to Add Bridges
Step 2: Edit Tor Configuration
Use obfs3 and obfs4 Bridges
Use meek_lite Bridges
Starting with Whonix ™ 14, meek_lite bridges are available. To use them, simply add one more line to the /usr/local/etc/torrc.d/50_user.conf file. Take note the bridge type is called meek_lite, not meek which is used in Tor Browser Bundle. 
Step 3: Enable Tor
Follow this procedure if it has not been previously completed.
Enable Tor using Anon Connection Wizard (easiest option).
Start Anon Connection Wizard.
Choose the Enable Tor option. Press next.
Step 4: Have /usr/local/etc/torrc.d/50_user.conf Changes Take Effect
Disable Tor using Anon Connection Wizard (safest option).
Start Anon Connection Wizard.
Choose the Disable Tor option. Press next.
Same as above.
Whonix ™ is Preventing Tor from Bootstrapping!
Refer to the related Whonix ™ has Slowed Tor Connections Dramatically! wiki entry. Bootstrapping problems can relate to nation state or ISP censorship of Tor, or relate to the Tor guard in operation. In the latter case, temporarily changing the Tor guard might resolve the issue.
If that is ineffective, users can also:
- Confirm minimum system requirements have been met for Whonix ™.
- Confirm the accuracy of the VM clock with sdwdate.
- Remove any changes that were made to the Whonix-Gateway ™ (
sys-whonix) torrc configuration, such as bridges, pluggable transports, seccomp, connection padding and so on.
- Test Tor functionality on the host.
- In Qubes-Whonix ™, test Tor functionality in a non-Whonix ™ AppVM.
- Increase the amount of RAM available to Whonix-Gateway ™ (
- Follow other Troubleshooting advice.
Can I Speed Up Tor or the Whonix-Gateway ™?
Is there a way to configure the number of nodes in a circuit and to allow selection according to their speeds?
Those who already know how to configure Tor in this way on the command line in vanilla Debian can follow the same procedure in Whonix-Gateway ™. This is not an endorsement for making these manual Tor changes because it is not recommended by Tor developers and thus the Whonix ™ team.  This is also the reason there are no instructions in the Whonix ™ documentation to manipulate Tor nodes in this way.
That said, if general instructions were found describing how to achieve this on the host, then the same procedure could simply be repeated in Whonix-Gateway ™.
Does Whonix ™ Modify Tor?
Although Whonix ™ does not modify Tor, the configuration file has been adapted for Whonix ™. To inspect the relevant files, check the following on Whonix-Gateway ™: 
Tor is not patched and the normal Tor deb package is used in Whonix ™ from deb.torproject.org.
Any changes to the Tor routing algorithm should be proposed, discussed and eventually implemented upstream in Tor on torproject.org.  If proposed changes are not adopted by The Tor Project, then the option to create a Tor fork  is available. Tor has already been forked at least once.
A general Whonix ™ design principle is to keep the Tor process as uniform as possible, in order to simplify any security audits. Diverging from this practice would introduce unnecessary complexity, possibly worsen fingerprinting or degrade anonymity, and limit Whonix ™ discussions to the security impacts of the modified routing algorithm. For these reasons, the Whonix ™ team is strongly disinclined to make any direct changes to the Tor package.
Can Whonix ™ Improve Tor?
As outlined in the previous section, Whonix ™ will not implement any changes to Tor directly and any suggested improvements or bug fixes are proposed upstream on torproject.org. This has already happened on occasion. Creating Whonix ™ is a difficult and time consuming endeavor, so Tor improvements are better left to dedicated, skilled developers who are more knowledgeable in this area.
Skilled coders can always provide upstream patches to Tor, or as a last resort, fork  it. Hypothetically, if a fork  developed a greater following than the original project due to proven security / anonymity benefits, then Whonix ™ would seriously consider making a switch.
- Why does Whonix ™ use Tor?
- Why is Tor slow?
- Censorship Circumvention - Configure (Private) (Obfuscated) Tor Bridges
- Hide Tor and Whonix ™ use from the ISP
- Control and Monitor Tor
- Hosting Tor Onion Services (any Hidden Webserver)
- Comparison of Tor with CGI Proxies, Proxy Chains and VPN Services
- Newer Tor Versions
Footnotes / References
/var/run/tor/log is a Tor configuration file specific to Whonix ™ and an alternative to /var/log/tor/log. The former only contains Tor's output since Whonix-Gateway ™ (
sys-whonix) last booted. The latter is a permanent log that persists across reboots. The former has a small usability advantage because it is shorter and should therefore contain more relevant information.
- whonixcheck check /var/lib/tor folder permission
UWT_DEV_PASSTHROUGH=1 curl 10.152.152.10:9100
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
fte example text to add to /usr/local/etc/torrc.d/50_user.conf.
fte is not yet supported in Whonix ™ 14; wait for the Whonix ™ 15 release. https://phabricator.whonix.org/T520
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed bridge fte 10.200.100.60:95128 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge fte 300.100.300.80:23521 4352e58420e68f5e40bf7c74faddccd9d1349413
- meek_lite actually uses a different implementation of obfs4proxy. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3
- Deferring to their expertise on the possible adverse anonymity effects.
- Changes to the configuration file are made by the anon-gw-anonymizer-config package.
- This means changes occur for all Tor users and not a subset relying on a particular distribution.
No comments for now due to spam. Use Whonix forums instead.
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.
Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)