Tor Documentation for Whonix Users

Whonix ®

Download

Windows Linux Mac VirtualBox KVM Qubes USB ISO (coming soon) More options Source Code

About

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

Docs

Documentation FAQ Troubleshooting

Community

Forums 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 Icon

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

Configuration

Introduction

Essential Tor Configuration:

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

Advanced Tor Configuration:

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

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

Edit Tor Configuration

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 Menu → Applications → Settings → /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

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://archive.ph/o/Aj1oi/https://www.torproject.org/download/download%23warning
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

Introduction

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

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://archive.ph/o/Aj1oi/https://www.torproject.org/download/download%23warning
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

Not required when using anon-log.

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

Watch Tor Log

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

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 (Not applicable at time of writing.)

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

If it is 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 investigate further, see #Configuration Check and #Log Analysis.

Permissions Fix

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 Menu → Xfce Terminal

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

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

3. Restart Tor.

Select your platform.

Non-Qubes-Whonix

Start Menu → Applications → Settings → Restart Tor

Qubes-Whonix

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

Terminal

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.

Non-Issues

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

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 Version Downgrade

It is usually not required to downgrade the Tor version. This should be only used in very specific cases to work around a bug or for testing.

1. Platform specific notice.

• non-Qubes users: No special notice.
• Qubes users: In Whonix-Gateway Template.

2. Update your package lists.

sudo apt update

3. Show available Tor versions.

apt list tor -a

Alternatively you could also look up the version number available from [https://packages.debian.org/bookworm /tor Debian's tor package].

4. Downgrade for example to Tor version 0.4.7.16-1.

Note: The version number was appropriate at time of writing but might need replacement in the future.

sudo apt install tor=0.4.7.16-1 tor-geoipdb=0.4.7.16-1

5. Platform specific notice.

• non-Qubes users: No special notice.
• Qubes users: Shut down Whonix-Gateway Template.

6. Reboot.

• non-Qubes users: A reboot of the Whonix-Gateway running Tor is required.
• Qubes users: A reboot of sys-whonix is required.

7. Done.

The process of Tor version downgrade has been completed.

Tor Consensus Re-Download

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

Advanced Topics

Tuning

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

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 : THIS wiki CHAPTER only is only supported by the community. Whonix developers are very unlikely to provide free support for this content. 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.

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:

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

Tor configuration for additional SocksPortss.

1. Edit Tor Configuration

2. Learn the syntax.

Only need to read this. No need to copy anything.

+SocksPort 127.0.0.1:port-number
+SocksPort 10.152.152.10:port-number

port-number will need to be replaced, which is documented below.

3. Add.

Here is an example that needs adjustment.

Notes:

• Keep gateway internal IP 10.152.152.10 as is.
• Replace port 9100 with the actual port for the additional SocksPorts you want to add.
• Adding 127.0.0.1 might not be strictly necessary but can be useful for testing.

+SocksPort 127.0.0.1:9100 +SocksPort 10.152.152.10:9100

4. Save.

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

Firewall configuration for additional SocksPortss.

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 Menu → Applications → Settings → User 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_short}} 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-gateway-17 → Whonix Global Firewall Settings

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

Start Menu → Applications → Settings → Global 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. Learn the syntax.

Only need to read this. No need to copy anything.

INTERNAL_OPEN_PORTS+=" port-number "

port-number will need to be replaced, which is documented below.

3. Add setting.

Notes:

• Replace port 9100 with the actual port for the additional SocksPorts you want to add.

INTERNAL_OPEN_PORTS+=" 9100 "

4. Save.

5. 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 Menu → Applications → System → Reload Whonix Firewall

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

Platform specific notice:

• Non-Qubes-Whonix: No special notice.
• Qubes-Whonix: Either a reboot or running replace-ips is required.
  • sudo /usr/lib/qubes-whonix/replace-ips

Done.

The additional SocksPort should now be functional.

For troubleshooting, see footnote.

Multiple Tor Daemons

TODO: document

Mostly undocumented.

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

Unsupported!

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"

If you do not wish to use tor-instance-create tool, you can do it manually creating the user who will run and own related files to tor's instance.

adduser --quiet --system --disabled-password --home "/var/lib/tor-instances/extradaemon1" --no-create-home --shell /bin/false --group --force-badname "_tor-extradaemon1" install -Z -d -m 02700 -o "_tor-extradaemon1" -g "_tor-extradaemon1" "/var/lib/tor-instances/extradaemon1" # Set SELinux security context, permission mode and ownership to the created user and group to the homedirectory install -d "/etc/tor/instances/extradaemon1"

Change user ownership of the created folder for the new tor instance.

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

Firewall settings change required.

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 Menu → Applications → Settings → User 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_short}} 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-gateway-17 → Whonix Global Firewall Settings

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

Start Menu → Applications → Settings → Global 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 Menu → Applications → System → Reload Whonix Firewall

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

5. Done.

The procedure is complete.

As we are creating a new tor instance we must to create a new torrc file inside our new tor instance directory.

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.

We create symlinks for auto-launch of the new instance

sudo systemctl enable "tor@extradaemon1.service"

We start the new tor instance:

sudo systemctl restart "tor@extradaemon1.service"

And we can check if the new instance is running

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

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, blackhole IP address. 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.

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

TODO: Replace blackhole-address.tld with an actual blackhole address.

MapAddress eixoaclv7qvnmu5rolbdwba65xpdiditdoyp6edsre3fitad777jr3ad.onion blackhole-address.tld

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 Menu → Applications → Settings → Reload 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

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

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 Menu → Applications → Settings → /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

Use obfs4 Bridges

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.

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.

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_short}} # 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_short}} 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

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

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.

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

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 Menu → Applications → System → Anon 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.

Choose the Enable Tor option. Press next.

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

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 Menu → Applications → Settings → Reload 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

Disable Tor

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 Menu → Applications → System → Anon 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.

Choose the Disable Tor option. Press next.

Reload Tor

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 Menu → Applications → Settings → Reload 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

Restart Tor.

Select your platform.

Non-Qubes-Whonix

Start Menu → Applications → Settings → Restart Tor

Qubes-Whonix

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

Terminal

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

See Vanguards.

UDP

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

Same as above.

DNS

Similar to above.

FAQ

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 (sys-whonix).
• 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?

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

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.

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:

• /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 Debian package and vanguards is installed by default in Whonix. (technical details)

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.

Tor Routing Algorithm

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:

• Anonymity Bibliography - Collection Anonymity Research
• Read the Tor blog as there are often blog posts discussing anonymity research such as blog post new low cost traffic analysis attacks and mitigations.

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

• Whonix Relationship With Upstream
• Why does Whonix use Tor?
• Placing Trust in Whonix
• Self Support First Policy
• Linux User Experience versus Commercial Operating Systems

See also:

• Does Whonix Modify Tor?
• Can Whonix Improve Tor?

How do I Change Other Tor Settings?

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

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 Self Support First Policy applies.

How do I Install the Latest Tor Version?

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

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

• anon-info → Show Tor Version Number
• anon-verify → Tor Configuration Check
• anon-log → Tor Log Analysis

See also:

• Network Obstacle
• Censorship Circumvention - Configure (Private) (Obfuscated) Tor Bridges

Tor Generic Bug Reproduction

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 bookworm inside a VM.
2. Install the tor Debian package.

Install package(s) tor following these instructions

1 Platform specific notice.

• Non-Qubes-Whonix: No special notice.
• Qubes-Whonix: In Template.

2 Update the package lists and upgrade the system .

sudo apt update && sudo apt full-upgrade

3 Install the tor package(s).

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

sudo apt install --no-install-recommends tor

4 Platform specific notice.

• Non-Qubes-Whonix: No special notice.
• Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .

5 Done.

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

1. Skip vanguards steps depending on whether the vanguards wiki page states that it is currently used by Whonix or not.
2. Install vanguards from the Debian bookworm repository. If needed, see footnote for installation instructions.
3. Make vanguards work with Tor. Unspecific to Whonix. See footnotes.
4. Attempt to reproduce the original issue.
5. 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.

Further Reading

• Why does Whonix use Tor?
• Why is Tor slow?
• Censorship Circumvention - Configure (Private) (Obfuscated) Tor Bridges
• Anon Connection Wizard
• Network Obstacle
• Hide Tor and Whonix use from the ISP
• Tor Controller - 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
• tor-ctrl-observer - Tor Connection Destination Viewer

Footnotes / References

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- 2024 ENCRYPTED SUPPORT LP

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 12 year success story and maybe DONATE!