Tor

From Whonix

Tor Icon

Does Whonix use Tor? Yes. Why? See Why does Whonix use Tor.

Configuration[edit]

Introduction[edit]

Essential Tor Configuration:

For enabling Tor, disabling Tor and using Bridges the user can use Anon Connection Wizard. [1]

Advanced Tor Configuration:

Tor configuration can also be modified by editing the Tor configuration file(s).

Info It is recommended for simplicity for most users that all unique user Tor configurations should be stored in Tor configuration file /usr/local/etc/torrc.d/50_user.conf and nowhere else. [2] Note that Whonix ™ will not modify /usr/local/etc/torrc.d/50_user.conf once it is created, therefore the user is responsible for adding or removing specific configurations in this file.

Configuration Drop-In Folders /etc/torrc.d/ and /usr/local/etc/torrc.d/ are a Whonix ™ specific feature. (technical details) Advanced users and packages specifically supporting Whonix ™ are free to use these folders, however other distributions such as Debian do not support it at time of writing. [3]

Edit Tor Configuration[edit]

Open file /usr/local/etc/torrc.d/50_user.conf in a text editor of your choice with sudoedit.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Tor User Config (Torrc)

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettings/usr/local/etc/torrc.d/50_user.conf

If you are using a terminal-only Whonix-Gateway ™, complete the following steps.

sudoedit /usr/local/etc/torrc.d/50_user.conf

Configuration Check[edit]

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 ™: sys-whonix).

anon-verify

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

Log Analysis[edit]

Introduction[edit]

Analysis of Tor's (and vanguards's) log can be useful if connectivity issues emerge.

Regarding log messages from vanguards, see also vanguards, Log Analysis.

anon-log[edit]

anon-log simplifies the manual dump Tor log command by only showing relevant log entries and no non-issues.

sudo anon-log

The output should be similar to the following.

tor.service:

Starting Anonymizing overlay network for TCP (multi-instance-master)...
Started Anonymizing overlay network for TCP (multi-instance-master).

/run/tor/log:

Jan 20 11:50:47.733 [notice] Tor 0.4.4.6 running on Linux with Libevent 2.1.8-stable, OpenSSL 1.1.1d, Zlib 1.2.11, Liblzma 5.2.4, and Libzstd 1.3.8.
Jan 20 11:50:47.733 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://www.torproject.org/download/download#warning
Jan 20 11:50:47.000 [notice] Bootstrapped 0% (starting): Starting
Jan 20 11:50:48.000 [notice] Starting with guard context "default"
Jan 20 11:50:48.000 [notice] Signaled readiness to systemd
Jan 20 11:50:48.000 [notice] Received reload signal (hup). Reloading config and resetting internal state.
Jan 20 11:50:48.000 [notice] Bootstrapped 5% (conn): Connecting to a relay
Jan 20 11:50:48.000 [notice] Bootstrapped 10% (conn_done): Connected to a relay
Jan 20 11:50:49.000 [notice] Bootstrapped 14% (handshake): Handshaking with a relay
Jan 20 11:50:49.000 [notice] Bootstrapped 15% (handshake_done): Handshake with a relay done
Jan 20 11:50:49.000 [notice] Bootstrapped 75% (enough_dirinfo): Loaded enough directory info to build circuits
Jan 20 11:50:49.000 [notice] Bootstrapped 90% (ap_handshake_done): Handshake finished with a relay to build circuits
Jan 20 11:50:49.000 [notice] Bootstrapped 95% (circuit_create): Establishing a Tor circuit
Jan 20 11:50:54.000 [notice] Bootstrapped 100% (done): Done

vanguards.service:

WARNING[Wed Jan 20 11:50:48 2021]: Tor daemon connection closed. Trying again...
NOTICE[Wed Jan 20 11:50:49 2021]: Vanguards 0.3.1 connected to Tor 0.4.4.6 using stem 1.7.1

Dump Tor Log[edit]

Not required when using anon-log. [4]

sudo journalctl -b --output cat --no-pager -u tor -u tor@default -u vanguards

Watch Tor Log[edit]

Users can also watch Tor's log as it is written.

sudo journalctl -f -b --output cat --no-pager -u tor -u tor@default -u vanguards

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

Connectivity Troubleshooting[edit]

To debug, try these commands in Whonix-Gateway (Qubes-Whonix ™: sys-whonix).

1. See Troubleshooting.

2. Run a Configuration Check.

3. Verbose run of systemcheck including leak tests. (These are just used as a connectivity test. There is no indication to suspect any leaks.)

systemcheck --verbose --leak-tests

4. Run a connectivity test. (Test connectivity independent from, without waiting for time synchronization being done.)

systemcheck --verbose --leak-tests --function check_tor_socks_port

5. Run a clock test.

sudo anondate-get

6. Running APT inside Whonix-Gateway. (Related: Operating System Software and Updates)

sudo apt update

If APT fails, it's a "lower level" issue, connectivity issue. (Qubes-Whonix ™: no need to look into Template, tinyproxy.)

7. "Forget" about ping.

8. Sometimes a Tor Consensus Re-Download can help.

9. Tor Log Analysis.

10. vanguards Log Analysis

11. See also Network Obstacle and Bridges.

12. Unnecessary use of Bridges.

Using Bridges if not really needed can cause connectivity issues. Users not living in censored areas should consider not using bridges. As mentioned on the Bridges wiki page:

Quote Roger Dingledine, cofounder of Tor:

[...] Bridges are less reliable and tend to have lower performance than other entry points. If you live in a uncensored area, they are not necessarily more secure than entry guards. [...]

13. See Tor Generic Bug Reproduction.

Tor not running[edit]

If if it reported that Tor is not running (such as by systemcheck Tor Running Check) then this means only that Tor is not running. This test result should not be over interpreted.

Tor not running means that the Tor process/program is currently not running indeed. This is completely unrelated to any clock issues. Even if the clock was very wrong, very slow in year 1900 or super fast in year 2100 this would not lead to Tor not running. Connectivity is a different issue. Tor would be running but might be unable to connect. If that was the case, there would be a different error message.

To independently verify that Tor is not running, the following command can be used on Whonix-Gateway ™.

sudo systemctl status tor@default

Reason for Tor not running could be that either Tor was stopped by the user or a configuration issue. To ivestigate further, see # Configuration Check and #Log Analysis.

Permissions Fix[edit]

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.

1. Open a terminal.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Xfce Terminal

If you are using a graphical Whonix ™ with XFCE, run.

Start MenuXfce Terminal

2. Apply a permissions fix for the Tor data folder.

sudo chown --recursive debian-tor:debian-tor /var/lib/tor

3. Restart Tor.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Restart Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsRestart Tor

If you are using a terminal-only Whonix-Gateway ™, press on Expand on the right.

Complete the following steps.

Restart Tor.

sudo service tor@default restart

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

anon-verify

The output should be similar to the following.

/===================================================================\
|                      Report Summary                               |
\===================================================================/
No error detected in your Tor configuration.

4. Done.

Error messages should no longer appear after completing these steps. [5]

Non-Issues[edit]

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 systemcheck, specifically the function check_tor_socks_port_reachability which checks if a Tor SocksPort is reachable by trying to fetch it using curl. [6] 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 ™ (sys-whonix) that is only available to Whonix-Workstation ™ because Whonix-Gateway ™ (sys-whonix) is firewalled. See /usr/bin/whonix_firewall or the Whonix ™ source code for further information.
[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 systemcheck's Tor Bootstrap Status Test, which uses Tor's ControlPort or CPFP.

Version Number[edit]

To discover what Tor version is currently in use, run the following command inside Whonix-Gateway ™ (Qubes-Whonix ™: sys-whonix).

anon-info

The output should be similar to the following.

INFO: version of the 'tor' package: 0.4.6.9-1~d11.bullseye+1

See also Newer Tor Versions.

Tor Consensus Re-Download[edit]

While this persists Tor Entry Guards, it results in Tor re-downloading the Tor Consensus document. Should usually not be required.

sudo anon-consensus-del

[7]

Advanced Topics[edit]

Tuning[edit]

Whonix-Gateway ™ can profit from RAM increase if a large number of circuits are created and Tor is kept busy. See RAM and Tuning.

Additional SocksPorts[edit]

Various custom SocksPorts have already been prepared. Those are documented here.

Adding additional on top of that is usually not required. Setting a socks user name has the same effect of establishing stream isolation as mentioned on the Stream Isolation wiki page (IsolateSOCKSAuth). Otherwise:

Community Support Only!:
Info

Community Support Only means Whonix ™ developers are unlikely to provide free support for wiki chapters or pages with this tag. See Community Support for further information, including implications and possible alternatives.

Adding additional Tor SocksPorts to /usr/local/etc/torrc.d/50_user.conf is non-intuitive. [8]

As noted in the Tor man page (man tor):

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: [9]

So to make sure that the SocksPort in the torrc does what you want, write it as +SocksPort.

After adding custom ports, a user would also have to edit the Whonix ™ firewall.

  1. open an incoming port for connections originating from Whonix-Workstation ™ in Whonix-Gateway ™ firewall
  2. Open an outgoing port for connections to Whonix-Gateway ™ in Whonix-Workstation ™ firewall

Multiple Tor Daemons[edit]

TODO: document

Mostly undocumented.

Extra complexity in Qubes due to non-persistence of root file system in App Qube which is undocumented.

Untested!

TODO: explain

The textual string extradaemon1 used below is to be understood an example word. It's not a constant. In other words, it's not a hardcoded name. Feel free to replicate/replace with a different name such as extradaemon2.

Create folder /etc/tor/instances/extradaemon1/ and folder /var/lib/tor-instances/extradaemon1.

sudo tor-instance-create "extradaemon1"

TODO: explain

sudo chown --recursive "_tor-extradaemon1:_tor-extradaemon1" "/var/lib/tor-instances/extradaemon1"

Firewall settings change required. [10]

1. Modify Whonix-Gateway ™ User Firewall Settings.

Note: If no changes have yet been made to Whonix ™ Firewall Settings, then the Whonix ™ User Firewall Settings File /usr/local/etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix ™, complete these steps.
In Whonix-Gateway ™ App Qube. Make sure folder /usr/local/etc/whonix_firewall.d exists.

sudo mkdir -p /usr/local/etc/whonix_firewall.d

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ App Qube (commonly called sys-whonix)Whonix ™ User Firewall Settings

If using a graphical Whonix-Gateway ™, complete these steps.

Start MenuApplicationsSettingsUser Firewall Settings

If using a terminal-only Whonix-Gateway ™, complete these steps.

In Whonix-Gateway ™, open the whonix_firewall configuration file in an editor.

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_gateway_default.conf.

Note: The Whonix ™ Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_gateway_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When {{project_name_long}} is updated, this
## file may be overwritten.

See also Whonix modular flexible .d style configuration folders.

To view the file, follow these instructions.

If using Qubes-Whonix ™, complete these steps.

Qubes App Launcher (blue/grey "Q")Template: whonix-gw-16Whonix Global Firewall Settings

If using a graphical Whonix-Gateway ™, complete these steps.

Start MenuApplicationsSettingsGlobal Firewall Settings

If using a terminal-only Whonix-Gateway ™, complete these steps.

In Whonix-Gateway ™, open the whonix_firewall configuration file in an editor.

nano /etc/whonix_firewall.d/30_whonix_gateway_default.conf

2. Add setting.

TOR_USER="$(id -u debian-tor) $(id -u _tor-extradaemon1)"

3. Save.

4. Reload Whonix-Gateway ™ Firewall.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Reload Whonix ™ Firewall

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemReload Whonix ™ Firewall

If you are using a terminal-only Whonix-Gateway ™, run.

sudo whonix_firewall

5. Done.

The procedure is complete.

TODO: explain

sudoedit /etc/tor/instances/extradaemon1/torrc

Paste the following content. Example.

SocksPort 0 HiddenServiceDir /var/lib/tor-instances/extradaemon1/hidden_service/ HiddenServicePort 80 10.152.152.11:80 HiddenServiceVersion 3

Save and exit.

TODO: explain

sudo systemctl enable "tor@extradaemon1.service"

TODO: explain

sudo systemctl restart "tor@extradaemon1.service"

TODO: explain

sudo systemctl status --no-block --no-pager "tor@extradaemon1.service"

Check if folder /var/lib/tor-instances/extradaemon1 exists. For example:

ls -la /var/lib/tor-instances/extradaemon1/

forum discussion: https://forums.whonix.org/t/what-is-the-best-way-to-have-more-than-one-tor-instance-in-whonix-gateway/14124

Blacklist Outgoing Connections to Select Domains[edit]

Advanced users might for unknown reasons select to blacklist outgoing connections to certain onion services. This can be done by instructing Tor to resolve a domain name to a dysfunctional IP address, in this case 127.0.0.1 (localhost). Since onion services do not have IP addresses and are only internally resolved by Tor through an IP address internal to Tor only, this blocking should be comprehensive.

This procedure could also be applied for clearnet domain names. However, in case of blacklisting outgoing connections to clearnet domain names, the blocking would be incomplete. Only DNS resolution would be blocked. IP based connections would still be possible.

Info This procedure is experimental. Testers only.

1. Open file /usr/local/etc/torrc.d/50_user.conf in a text editor of your choice with sudoedit.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Tor User Config (Torrc)

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettings/usr/local/etc/torrc.d/50_user.conf

If you are using a terminal-only Whonix-Gateway ™, complete the following steps.

sudoedit /usr/local/etc/torrc.d/50_user.conf

2. Use the MapAddress configuration option.

Add the following configuration text to the file. The following is an example onion service that is added to /usr/local/etc/torrc.d/50_user.conf Tor configuration file.

Note: Replace eixoaclv7qvnmu5rolbdwba65xpdiditdoyp6edsre3fitad777jr3ad.onion with the actual onion service that should be blacklisted.

MapAddress eixoaclv7qvnmu5rolbdwba65xpdiditdoyp6edsre3fitad777jr3ad.onion 127.0.0.1

3. Reload Tor.

After changing Tor configuration, Tor must be reloaded for changes to take effect.

Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Reload Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsReload Tor

If you are using a terminal-only Whonix-Gateway ™, click HERE for instructions.

Complete the following steps.

Reload Tor.

sudo service tor@default reload

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

sudo -u debian-tor tor --verify-config

The output should be similar to the following.

Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf".
Configuration was valid

4. Done.

The procedure of adding an onion service to the blacklist of outgoing connections has been completed.

Entry Guards[edit]

This entry has been moved here.

Manual Bridge Configuration[edit]

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[edit]

Open file /usr/local/etc/torrc.d/50_user.conf in a text editor of your choice with sudoedit.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Tor User Config (Torrc)

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettings/usr/local/etc/torrc.d/50_user.conf

If you are using a terminal-only Whonix-Gateway ™, complete the following steps.

sudoedit /usr/local/etc/torrc.d/50_user.conf

Step 2: Edit Tor Configuration[edit]

Use obfs4 Bridges[edit]

1. Open /usr/local/etc/torrc.d/50_user.conf in an editor.

Copy and paste the following text to enable the use of obfs4 bridges. [11] [12]

UseBridges 1 ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

2. Add the bridge IP addresses that were sourced in the Finding a Bridge and Choosing the Right Protocol section.

Copy and paste the IP addresses to the very bottom of /usr/local/etc/torrc.d/50_user.conf, after the ClientTransportPlugin entries. Users must ensure that "bridge" appears at the beginning of each line.

Info In the obfs4 example below:

  • Do not copy and paste this list of bridge entries to the 50_user.conf file. They will not work.
  • Retrieve obfs4 bridges from The Tor Project before editing this file.
  • Capitalization in the 50_user.conf file matters. For example, bridges will not connect if users type "bridge" instead of "Bridge".

Obfs4 example text to add to /usr/local/etc/torrc.d/50_user.conf.

Bridge obfs4 192.235.207.85:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0 Bridge obfs4 34.218.26.20:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0 Bridge obfs4 161.217.177.95:10703 B3B8009D01BB7E5FDFAEC cert=4RaIqGiOytEXm6Hw iat-mode=0

The sample text for a complete obfs4 torrc file is below. Check your file is similar, except for the specific bridge entries.

# This file is part of {{project_name_long}} # Copyright (C) 2012 - 2013 adrelanos
# See the file COPYING for copying conditions.

# Use this file for your user customizations.
# Please see /usr/local/etc/torrc.d/50_user.conf.examples for help, options, comments etc.

# Anything here will override {{project_name_long}} own Tor config customizations in /usr/share/tor/tor-service-defaults-torrc

# Enable Tor through setup-dist or manually uncomment "DisableNetwork 0" by
# removing the # in front of it.
DisableNetwork 0
UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

Bridge obfs4 192.235.207.85:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0
Bridge obfs4 34.218.26.20:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0
Bridge obfs4 161.217.177.95:10703 B3B8009D01BB7E5FDFAEC cert=4RaIqGiOytEXm6Hw iat-mode=0

[13]

3. After /usr/local/etc/torrc.d/50_user.conf editing is finished, save and exit.

<Ctrl-X> --> press Y --> <Enter>

Use meek_lite Bridges[edit]

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. [14]

1. Open /usr/local/etc/torrc.d/50_user.conf in an editor.

Copy and paste the following text to enable meek_lite bridges.

UseBridges 1 ClientTransportPlugin meek_lite exec /usr/bin/obfs4proxy

2. Add a meek_lite bridge to the configuration file.

An example of meek_lite text that must be added to the /usr/local/etc/torrc.d/50_user.conf file is below. The bridge in this example is functional, so a search for other meek_lite bridges is unnecessary.

Bridge meek_lite 0.0.2.0:2 B9E7141C594AF25699E0079C1F0146F409495296 url=https://d2cly7j4zqgua7.cloudfront.net/ front=a0.awsstatic.com

3. After /usr/local/etc/torrc.d/50_user.conf editing is finished, save and exit.

<Ctrl-X> --> press Y --> <Enter>

Step 3: Enable Tor[edit]

Follow this procedure if it has not been previously completed.

Enable Tor using Anon Connection Wizard (easiest option).

Start Anon Connection Wizard.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Anon Connection Wizard

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemAnon Connection Wizard

If you are using a terminal emulator (such as for example xfce4-terminal) on Whonix-Gateway ™, type.

lxsudo anon-connection-wizard

If you are using a CLI Whonix-Gateway ™, see footnote. [15]

Choose the Enable Tor option. Press next.

Step 4: Have /usr/local/etc/torrc.d/50_user.conf Changes Take Effect[edit]

Reload Tor.

After changing Tor configuration, Tor must be reloaded for changes to take effect.

Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Reload Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsReload Tor

If you are using a terminal-only Whonix-Gateway ™, click HERE for instructions.

Complete the following steps.

Reload Tor.

sudo service tor@default reload

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

sudo -u debian-tor tor --verify-config

The output should be similar to the following.

Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf".
Configuration was valid

Tor Functions[edit]

Disable Tor[edit]

Disable Tor using Anon Connection Wizard (safest option).

Start Anon Connection Wizard.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Anon Connection Wizard

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemAnon Connection Wizard

If you are using a terminal emulator (such as for example xfce4-terminal) on Whonix-Gateway ™, type.

lxsudo anon-connection-wizard

If you are using a CLI Whonix-Gateway ™, see footnote. [16]

Choose the Disable Tor option. Press next.

Reload Tor[edit]

Reload Tor.

After changing Tor configuration, Tor must be reloaded for changes to take effect.

Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Reload Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsReload Tor

If you are using a terminal-only Whonix-Gateway ™, click HERE for instructions.

Complete the following steps.

Reload Tor.

sudo service tor@default reload

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

sudo -u debian-tor tor --verify-config

The output should be similar to the following.

Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf".
Configuration was valid

Restart Tor[edit]

Restart Tor.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Restart Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsRestart Tor

If you are using a terminal-only Whonix-Gateway ™, press on Expand on the right.

Complete the following steps.

Restart Tor.

sudo service tor@default restart

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

anon-verify

The output should be similar to the following.

/===================================================================\
|                      Report Summary                               |
\===================================================================/
No error detected in your Tor configuration.

vanguards[edit]

See Vanguards.

UDP[edit]

Ambox notice.png The Tor software does not support UDP. The feature request UDP over Tor was created in 2013 and closed as won't fix by upstream, The Tor Project in 2018. It is therefore highly unlikely that the UDP over Tor feature will ever be implemented. This is unspecific to Whonix ™.

Tor provides a DnsPort but that is unrelated.

If UDP is urgently required in Whonix ™, a limited workaround is provided. For the most secure method, see Tunnel UDP over Tor.

ICMP[edit]

Same as above.

FAQ[edit]

Whonix ™ is Preventing Tor from Bootstrapping![edit]

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:

Can I Speed Up Tor or the Whonix-Gateway ™?[edit]

Is there a way to configure the number of nodes in a circuit and to allow selection according to their speeds?

Info Reminder: Whonix ™ Reliance on Debian (and Tor) - "Whonix ™ is not a stripped down version of Debian; anything possible in "vanilla" Debian GNU/Linux can be replicated in Whonix ™." Tor configurations are not limited by using Whonix ™.

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. [17] 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?[edit]

Info Tor is an anonymizer developed by The Tor Project. Tor Browser is a web browser developed by the Tor Project which is optimized for privacy. Please do not confuse Tor with Tor Browser when conversing about Whonix ™ topics.

For differences of Tor Browser by Tor Project compared to Tor Browser in Whonix ™ see Whonix ™ Tor Browser Differences.

Info Whonix ™ does not modify the Tor package itself.

Although Whonix ™ does not modify Tor, the Tor configuration file has been adapted for Whonix ™. To inspect the relevant files, check the following on Whonix-Gateway ™: [18]

  • /etc/tor/torrc file.
  • /etc/torrc.d folder.
  • /usr/local/etc/torrc.d/ folder.
  • /usr/share/tor/tor-service-defaults-torrc file.

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. [19] If proposed changes are not adopted by The Tor Project, then the option to create a Tor fork [20] 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?[edit]

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 [20] it. Hypothetically, if a fork [20] developed a greater following than the original project due to proven security / anonymity benefits, then Whonix ™ would seriously consider making a switch.

Tor Routing Algorithm[edit]

Quote Tor Project FAQ Can I control which nodes (or country) are used for entry/exit? (bold and underline added)

Yes. You can set preferred entry and exit nodes as well as inform Tor which nodes you do not want to use. The following options can be added to your config file torrc or specified on the command line:

[...]

We recommend you do not use these — they are intended for testing and may disappear in future versions. You get the best security that Tor can provide when you leave the route selection to Tor; overriding the entry / exit nodes can mess up your anonymity in ways we don't understand.

To make changes to the Tor routing algorithm which benefit anonymity and not actually worsen anonymity it is required to be more clever than the Tor developers. Many questions, suggestions and discussions online only scratch the surface and are unaware of the informational resources:

The following resources describe the organizational structure of the Whonix ™ project in relation to The Tor Project, Debian and other upstream sources.

See also:

How do I Change Other Tor Settings?[edit]

Questions are often raised in forums about how other Tor-specific changes can be made in Whonix ™, such as excluding specific exit nodes. [21]

In many cases, making such changes is already documented Whonix ™ Documentation. In other cases such changes are discouraged.

In all instances:

  1. Changes must be made to the Tor configuration file as per Edit Tor Configuration.
  2. Refer to the Tor Project Manual for specific configuration details.

For example, to exclude exit nodes from the Five Eyes countries the Tor configuration would include the following lines:

Discouraged!

ExcludeExitNodes {us},{au},{ca},{nz},{gb}
StrictNodes 1

A Configuration Check should be run afterwards inside Whonix-Gateway ™ (Qubes-Whonix ™: sys-whonix) to confirm there are no Tor configuration syntax errors. As these configurations are specific to Tor and unspecific to Whonix ™), the Free Support Principle applies.

How do I Install the Latest Tor Version?[edit]

Follow the instructions here to install later Tor versions from either:

  • the Whonix ™ repository; or
  • Tor Project APT repositories; or
  • Tor Project source code.

Troubleshooting[edit]

The following helper tools and documentation chapters might be of assistance.

See also:

Tor Generic Bug Reproduction[edit]

Based on Bug Report Recommendations, specifically Generic Bug Reproduction. Similar to Troubleshooting advice "Try a non-Whonix VM".

The following results in a manual reproduction of the Whonix ™ Tor Integration without involving Whonix ™. This enables the user to remove Whonix ™ as a possible source of issues and reduces the added complexity of Whonix ™.

  1. Install Debian bullseye inside a VM.
  2. Install the tor Debian package.

Install package(s) tor.

A. Update the package lists and upgrade the system.

sudo apt update && sudo apt full-upgrade

B. Install the tor package(s).

Using apt command line parameter --no-install-recommends is in most cases optional.

sudo apt install --no-install-recommends tor

C. Done.

The procedure of installing package(s) tor is complete.

  1. Install vanguards from the Debian bullseye repository. If needed, see footnote for installation instructions. [22]
  2. Make vanguards work with Tor. Unspecific to Whonix ™. See footnotes. [23] [24]
  3. Attempt to reproduce the original issue.
  4. If the issue is reproducible without involving Whonix ™ then the issue is unspecific to Whonix ™. This enables the user to utilize upstream (original authors of Tor software, Tor community) resources. Please use Search Engines and see Documentation First. If needed, submit an upstream support request or bug report. In this case, mentioning Whonix ™ is discouraged. Mentioning Whonix ™ even though it is an issue unspecific to Whonix ™ could add confusion. [25]

Further Reading[edit]

Footnotes / References[edit]

  1. Anon Connection Wizard stores its configuration file file /usr/local/etc/torrc.d/40_tor_control_panel.conf.
  2. /usr/local/etc/torrc.d/40_tor_control_panel.conf is auto generated. It can be examined but changes should only be made to /usr/local/etc/torrc.d/50_user.conf.
  3. Debian feature request: add torrc.d configuration directory
    • -b: shortcut for journalctl --boot which shows only log entries from current boot. Not from previous boots.
    • --output cat: Prevention of duplicate timestamp per log line. Prevent journalctl from adding a timestamp to the log output since this is unnecessary since Tor already adds its own timestamp to the log.
    • --no-pager: Dump log to stdout. No scrolling.
    • tor: multi-instance-master
    • tor@default: actual Tor process
    • vanguards: add-on, see vanguards
  4. systemcheck /var/lib/tor folder permission
  5. UWT_DEV_PASSTHROUGH=1 curl 10.152.152.10:9100
  6. anon-consensus-del (and its helper-script anon-consensus-del-files) is just a script to automate the following steps for better usability. It does in essence the following this:
    sudo systemctl stop tor@default
    sudo su
    cd /var/lib/tor
    rm /var/lib/tor/cached-*
    sudo systemctl restart tor@default
  7. https://gitlab.torproject.org/legacy/trac/-/issues/15261
  8. https://gitlab.torproject.org/legacy/trac/-/issues/15261#comment:1
  9. On Whonix-Gateway ™, by default no linux username other than `debian-tor` are permitted to connect using clearnet. The Tor process is by default the only thing running under linux user name `debian-tor`. Therefore the new user under which the additional Tor daemon will run needs the same permission in Whonix-Gateway Firewall.
  10. obfs3 bridges have been deprecated by upstream, The Tor Project in favor of obfs4.
  11. ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
  12. fte example text to add to /usr/local/etc/torrc.d/50_user.conf. fte is supported in Whonix ™ 15, but further testing is required; see: 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
  13. meek_lite actually uses a different implementation of obfs4proxy. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3
  14. Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support yet. It is therefore unavailable on Whonix-Gateway ™ CLI. Use setup-dist instead; note that functionality is limited and does not support Bridges.
  15. Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support yet. It is therefore unavailable on Whonix-Gateway ™ CLI. Use setup-dist instead; note that functionality is limited and does not support Bridges.
  16. Deferring to their expertise on the possible adverse anonymity effects.
  17. Changes to the configuration file are made by the anon-gw-anonymizer-config package.
  18. This means changes occur for all Tor users and not a subset relying on a particular distribution.
  19. 20.0 20.1 20.2 https://en.wikipedia.org/wiki/Fork_(software_development)
  20. https://forums.whonix.org/t/how-to-set-an-exit-node-in-wonix-of-qubesos/9070
  21. Install package(s) vanguards.

    A. Update the package lists and upgrade the system.

    sudo apt update && sudo apt full-upgrade

    B. Install the vanguards package(s).

    Using apt command line parameter --no-install-recommends is in most cases optional.

    sudo apt install --no-install-recommends vanguards

    C. Done.

    The procedure of installing package(s) vanguards is complete.

  22. 1. Open file /etc/tor/vanguards.conf in an editor with administrative (root) write permissions.

    This box uses sudoedit for better security. This is an example and other tools can also achieve the same goal. If this example does not work for you or if you are not using Whonix ™, please refer to this link.

    sudoedit /etc/tor/vanguards.conf

    2. change control_socket = to control_socket = /run/tor/control

    3. Save.

    4. Restart vanguards.

    sudo systemctl restart vanguards

  23. https://github.com/mikeperry-tor/vanguards/issues/47
  24. The reader considering a Whonix ™ specific issue while there cannot be one.