Actions

Tor

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

Edit Tor Configuration[edit]


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

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 Menu -> Applications -> Settings -> /usr/local/etc/torrc.d/50_user.conf

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

sudo nano /usr/local/etc/torrc.d/50_user.conf

Log Analysis[edit]

Introduction[edit]

Analysis of Tor's log can be useful if connectivity issues emerge.

Open Tor Log[edit]

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

Open /var/run/tor/log in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run.

kdesudo kwrite /var/run/tor/log

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

sudo nano /var/run/tor/log

Watch Tor Log[edit]

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

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) -> Konsole

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

Start Menu -> Applications -> System -> Konsole

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 Menu -> Applications -> Settings -> Restart 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.

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

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 whonixcheck, specifically the function check_tor_socks_port_reachability which checks if a Tor SocksPort is reachable by trying to fetch it using curl. [3] No warnings appear if the function works correctly.

[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-Workstations 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 whonixcheck'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.3.4.8-1~d90.stretch+1

Advanced Topics[edit]

Additional SocksPorts[edit]

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

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

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


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

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 Menu -> Applications -> Settings -> /usr/local/etc/torrc.d/50_user.conf

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

sudo nano /usr/local/etc/torrc.d/50_user.conf

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

Reload Tor.

After editing /usr/local/etc/torrc.d/50_user.conf, 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 Menu -> Applications -> Settings -> Reload Tor

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

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

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 /usr/local/etc/torrc.d/50_user.conf.

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 Menu -> Applications -> Settings -> /usr/local/etc/torrc.d/50_user.conf

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

sudo nano /usr/local/etc/torrc.d/50_user.conf

Step 2: Edit Tor Configuration[edit]

Use obfs3 and obfs4 Bridges[edit]

Open /usr/local/etc/torrc.d/50_user.conf in an editor, then copy and paste the following text to enable the use of obfs3 and obfs4 bridges. [6]

UseBridges 1
ClientTransportPlugin obfs3, obfs4 exec /usr/bin/obfs4proxy

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


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

bridge obfs3 109.195.132.77:22321 4352e58420e68f5e40bf7c74faddccd9d1349413
bridge obfs3 55.32.27.22:38123  4352e58420e68f5e40bf7c74faddccd9d1349413
bridge obfs3 192.24.131.513:62389 4352e58420e68f5e40bf7c74faddccd9d1349413

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 Whonix
# 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 Whonix's own Tor config customizations in /usr/share/tor/tor-service-defaults-torrc

# Enable Tor through whonixsetup or manually uncomment "DisableNetwork 0" by
# removing the # in front of it.
DisableNetwork 0
UseBridges 1
ClientTransportPlugin obfs3, 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

[7]

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]

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

Open /usr/local/etc/torrc.d/50_user.conf in an editor, then copy and paste the following text to enable meek_lite bridges.

ClientTransportPlugin meek_lite exec /usr/bin/obfs4proxy

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

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 the whonix-setup-wizard.

Start whonixsetup.

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

Qubes App Launcher (blue/grey "Q") -> Whonix-Gateway ProxyVM (commonly named 'sys-whonix') -> Whonix Setup

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

Start Menu -> Applications -> System -> Whonix Setup Wizard

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

sudo whonixsetup

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 editing /usr/local/etc/torrc.d/50_user.conf, 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 Menu -> Applications -> Settings -> Reload Tor

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

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 whonix-setup-wizard (safest option).

Start whonix-setup-wizard.

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

Qubes App Launcher (blue/grey "Q") -> Whonix-Gateway ProxyVM (commonly named 'sys-whonix') -> Whonix Setup

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

Start Menu -> Applications -> System -> Whonix Setup Wizard

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

sudo whonixsetup

Choose the Disable Tor option. Press next.

Reload Tor[edit]

Reload Tor.

After editing /usr/local/etc/torrc.d/50_user.conf, 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 Menu -> Applications -> Settings -> Reload Tor

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

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 Menu -> Applications -> Settings -> Restart 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.

UDP[edit]

Further Reading[edit]

Footnotes / References[edit]

  1. /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.
  2. whonixcheck check /var/lib/tor folder permission
  3. UWT_DEV_PASSTHROUGH=1 curl 10.152.152.10:9100
  4. https://trac.torproject.org/projects/tor/ticket/15261
  5. https://trac.torproject.org/projects/tor/ticket/15261#comment:1
  6. ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
  7. 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
  8. meek_lite actually uses a different implementation of obfs4proxy. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3
  9. https://trac.torproject.org/projects/tor/ticket/7830

Random News:

We are looking for video production specialists to help create demonstration, promotional and conceptual videos or tutorials.


https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)