Tor: Difference between revisions

From Whonix
Jump to navigation Jump to search
[unchecked revision][checked revision]
Content added Content deleted
(capitalization)
 
(361 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Header}}
{{Header}} {{title|title=
Tor Documentation for {{project_name_long}} Users
{{#seo:
}} {{#seo:
|description=Notes about Tor (The Onion Router) on Log Analysis, Non-Persistent Entry Guards, Blacklist Certain Onion Services from Connecting, Additional SocksPorts, UDP and more.
|description=Notes about Tor (The Onion Router) on Log Analysis, Non-Persistent Entry Guards, Blacklist Certain Onion Services from Connecting, Additional SocksPorts, UDP and more.
|image=Iconfinder_tor_386502.svg
|image=https://www.whonix.org/w/images/3/32/Menger-702837640.jpg
}} [[File:Iconfinder_tor_386502.svg|Tor Icon|200px|thumb]] {{intro|
Does Whonix use Tor? Yes. Why? See [[Why_does_Whonix_use_Tor|Why does Whonix use Tor]].
}}
}}
= Configuration =
== Introduction ==
<u>Essential Tor Configuration</u>:


For enabling Tor, disabling Tor and using [[Bridges]] the user can use [[Anon Connection Wizard]]. <ref>
= Version Number =
[[Anon Connection Wizard]] stores its configuration file file <code>/usr/local/etc/torrc.d/40_tor_control_panel.conf</code>.
To find out what Tor version you are running, run the following command inside Whonix-Gateway.
</ref>


<u>Advanced Tor Configuration</u>:
{{CodeSelect|code=

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

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = It is recommended for simplicity for most users that <u>all</u> unique user Tor configurations should be stored in Tor configuration file <code>/usr/local/etc/torrc.d/50_user.conf</code> and nowhere else. <ref>
<code>/usr/local/etc/torrc.d/40_tor_control_panel.conf</code> is auto generated. It can be examined but changes should only be made to <code>/usr/local/etc/torrc.d/50_user.conf</code>.
</ref> Note that {{project_name_short}} will <u>not</u> modify <code>/usr/local/etc/torrc.d/50_user.conf</code> once it is created, therefore the user is responsible for adding or removing specific configurations in this file.
}}
}}


[[Configuration_Files#Configuration_Drop-In_Folders|Configuration Drop-In Folders]] <code>/etc/torrc.d/</code> and <code>/usr/local/etc/torrc.d/</code> are a {{project_name_short}} specific feature. ([[Dev/Tor#Tor_Config_Files|technical details]]) Advanced users and packages specifically supporting {{project_name_short}} are free to use these folders, however other distributions such as Debian do not support it at time of writing. <ref>
Should show something like this.
Debian feature request: [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=866187 add torrc.d configuration directory]
</ref>


== Edit Tor Configuration ==
<pre>
{{Open /usr/local/etc/torrc.d/50 user.conf}}
0.2.8.6-1~d80.jessie+1
</pre>


== Configuration Check ==
= Permissions on directory /var/run/tor are too permissive Error =
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 {{project_name_gateway_long}} ([[Qubes|{{q_project_name_long}}]]: <code>{{project_name_gateway_vm}}</code>).
To find out if you are affected by the {{Code2|Permissions on directory /var/run/tor are too permissive Error}}<ref>
https://trac.torproject.org/projects/tor/ticket/19824
</ref>, run the following command inside Whonix-Gateway. (In Qubes, in sys-whonix.)


{{CodeSelect|code=
<pre>
anon-verify
sudo cat /var/run/tor/log | grep -i permissive
}}
</pre>


If you are affected, it would show something like the following.
The output should be similar to the following.


<pre>
<pre>
/===================================================================\
Aug 03 17:36:33.000 [warn] Permissions on directory /var/run/tor are too permissive.
| 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
=====================================================================
</pre>
</pre>


= Log Analysis =
The only workaround (needs to be manually re-done after every reboot) for now.
== Introduction ==
Analysis of Tor's (and [[vanguards|vanguards]]'s) log can be useful if connectivity issues emerge.

Regarding log messages from vanguards, see also [[vanguards#Log_Analysis|vanguards, Log Analysis]].

== anon-log ==
<code>anon-log</code> simplifies the manual [[#Dump Tor Log|dump Tor log]] command by only showing relevant log entries and no [[#Non-Issues|non-issues]].


{{CodeSelect|code=
{{CodeSelect|code=
sudo anon-log
sudo chmod --recursive 700 /var/run/tor
}}
}}


The output should be similar to the following.
= Log Analysis =
== Introduction ==
Analysis of Tor's log can be useful in case of connectivity issues.


<pre>
== Open Tor Log ==
tor.service:
* /var/log/tor/log - persistent Tor log
* /var/run/tor/log - Tor log since last boot


Starting Anonymizing overlay network for TCP (multi-instance-master)...
{{open with root rights|filename=
Started Anonymizing overlay network for TCP (multi-instance-master).
/var/run/tor/log
}}


/run/tor/log:
<ref>

{{Code2|/var/run/tor/log}} is a Whonix Tor configuration specific file. An alternative to {{Code2|/var/log/tor/log}}. The former only contains Tor's output since last boot of Whonix-Gateway. The latter is a permanent log that persists across reboots. The former has a small usability advantage. It is shorter. Should therefore contain more relevant information.
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
</pre>

== Dump Tor Log ==
Not required when using [[#anon-log|anon-log]]. <ref>
* <code>-b</code>: shortcut for <code>journalctl</code> <code>--boot</code> which shows only log entries from current boot. Not from previous boots.
* <code>--output cat</code>: Prevention of duplicate timestamp per log line. Prevent <code>journalctl</code> from adding a timestamp to the log output since this is unnecessary since Tor already adds its own timestamp to the log.
* <code>--no-pager</code>: Dump log to stdout. No scrolling.
* <code>tor</code>: multi-instance-master
* <code>tor@default</code>: actual Tor process
* <code>vanguards</code>: add-on, see [[vanguards|vanguards]]
</ref>
</ref>

{{CodeSelect|code=
sudo journalctl -b --output cat --no-pager -u tor -u tor@default -u vanguards
}}


== Watch Tor Log ==
== Watch Tor Log ==
You can also watch Tor's log as it's being written.
Users can also watch Tor's log as it is written.


{{CodeSelect|code=
{{CodeSelect|code=
sudo journalctl -f -b --output cat --no-pager -u tor -u tor@default -u vanguards
sudo tail -f /var/run/tor/log
}}
}}


This is especially useful in combination with another terminal tab and [[#Reload Tor|reloading Tor]].
This command is especially useful when Tor is reloaded or restarted simultaneously in another terminal window.

To [[#Reload Tor|reload Tor]], run the following command.


{{CodeSelect|code=
{{CodeSelect|code=
Line 68: Line 140:
}}
}}


Or [[#Restart Tor|restarting Tor]].
To [[#Restart Tor|restart Tor]], run the following command.


{{CodeSelect|code=
{{CodeSelect|code=
Line 74: Line 146:
}}
}}


= Connectivity Troubleshooting =
== Non-Issues ==
To debug, try these commands in {{project_name_gateway_short}} ([[Qubes|{{q_project_name_short}}]]: <code>{{project_name_gateway_vm}}</code>).
{| class="wikitable" style="background-color: #fff;text-align: center"


{{Box|text=
! message / question
'''1.''' See [[Troubleshooting]].
! answer

'''2.''' [[#Configuration Check|Run a Configuration Check]].

'''3.''' Verbose run of [https://www.kicksecure.com/wiki/Systemcheck systemcheck] including leak tests. (These are just used as a connectivity test. There is no indication to suspect any leaks.)

{{CodeSelect|code=
systemcheck --verbose --leak-tests
}}

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

{{CodeSelect|code=
systemcheck --verbose --leak-tests --function check_tor_socks_port
}}

'''5.''' Run a clock test.

{{CodeSelect|code=
sudo anondate-get
}}

'''6.''' Running APT inside {{project_name_gateway_short}}. (Related: [[Operating System Software and Updates]])

{{CodeSelect|code=
sudo apt update
}}

If APT fails, it's a "lower level" issue, connectivity issue. ([[Qubes|{{q_project_name_short}}]]: no need to look into Template, tinyproxy.)

'''7.''' [[Whonix-Workstation_Firewall#Ping|"Forget" about <code>ping</code>.]]

'''8.''' Sometimes a [[#Tor Consensus Re-Download|Tor Consensus Re-Download]] can help.

'''9.''' [[Tor#Log_Analysis|Tor Log Analysis]].

'''10.''' [[vanguards|vanguards]] L[[Vanguards#Log_Analysis|og 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:

[https://lists.torproject.org/pipermail/tor-talk/2012-May/024378.html Quote] Roger Dingledine, cofounder of Tor:

<blockquote>[...] 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. [...]</blockquote>

'''13.''' See [[#Tor Generic Bug Reproduction|Tor Generic Bug Reproduction]].
}}

{{Anchor|tor not running}}
= Tor not running =
If it is reported that Tor is not running (such as by [https://www.kicksecure.com/wiki/Systemcheck systemcheck] <code>Tor Running Check</code>) 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 {{project_name_gateway_short}}.

{{CodeSelect|code=
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.

<pre>
Oct 24 07:22:15.693 [warn] Directory /var/lib/tor/.tor cannot be read: Permission denied
</pre>

<pre>
Oct 25 12:35:07.460 [warn] Directory /var/lib/tor cannot be read: Permission denied
</pre>

<pre>
Oct 25 12:35:07.460 [warn] Failed to parse/validate config: Couldn't access private data directory "/var/lib/tor"
</pre>

Then apply the following steps.

{{Box|text=
'''1.''' {{Open_a__product_gw_terminal}}

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

{{CodeSelect|code=
sudo chown --recursive debian-tor:debian-tor /var/lib/tor
}}

'''3.''' {{Restart_Tor}}

'''4.''' Done.

Error messages should no longer appear after completing these steps. <ref>
[https://phabricator.whonix.org/T855 systemcheck /var/lib/tor folder permission]
</ref>
}}

= Non-Issues =
{| class="wikitable" style="background-color: #fff;text-align: left"

! '''Message / Question'''
! '''Answer'''


|-
|-
| <u>{{Code2|Am I compromised? Does Tor's log report leaks?}}
| <u>{{Code2|Am I compromised? Does Tor's log report leaks?}}
| Tor's output is conceptually not a tool to find out about serious issues such as compromise or leaks.</u>
| Tor's output is an ineffective tool for discovering serious issues such as a compromise or leaks.</u>


|-
|-
| {{Code2|[WARN] Socks version 71 not recognized. (Tor is not an http proxy.)}}
| {{Code2|[WARN] Socks version 71 not recognized. (Tor is not an http proxy.)}}
|
|
This is caused by [[whonixcheck]] (by function {{Code2|check_tor_socks_port_reachability}}). It checks if a Tor SocksPort is reachable by trying to fetch it using curl. <ref>
This warning is caused by [https://www.kicksecure.com/wiki/Systemcheck systemcheck], specifically the function {{Code2|check_tor_socks_port_reachability}} which checks if a Tor SocksPort is reachable by trying to fetch it using curl. <ref>
{{CodeSelect|code=
{{CodeSelect|code=
{{Curl_Plain}} 10.152.152.10:9100
{{Curl_Plain}} 10.152.152.10:9100
}}
}}
</ref> No warnings appear if the function works correctly.
</ref> It will not report anything if it worked, but would complain if it failed.


|-
|-
| {{Code2|[warn] Socks version 71 not recognized. (This port is not an HTTP proxy; did you want to use HTTPTunnelPort?)}}
| {{Code2|[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]}} (Or other port number or DnsPort or TransPort.)
| Similar to above.
| This is not of concern. Tor really listens on that IP/port. It is Whonix-Gateway's network interface, that is only available to Whonix-Workstations, because it is an internal network with Whonix-Workstation and because Whonix-Gateway is firewalled (see ''{{WhonixFirewall}}'' or in Whonix source code).


|-
|-
| {{Code2|[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.
| {{Code2|[NOTICE] New control connection opened. [2 duplicates hidden]}} (Or more duplicates.)
| This notice is not a concern because Tor really listens on that IP/port - it is the internal network interface for {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>) that is only available to {{project_name_workstation_long}} because {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>) is firewalled. See ''{{W_Firewall}}'' or the {{project_name_short}} source code for further information.
| This is not of concern. This is caused by [[whonixcheck]]'s Tor Bootstrap Status Test, which uses Tor's ControlPort or [[Dev/CPFP|CPFP]].

|-
| {{Code2|[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 [https://www.kicksecure.com/wiki/Systemcheck systemcheck]'s Tor Bootstrap Status Test, which uses Tor's ControlPort or [[Dev/onion-grater|CPFP]].


|}
|}


= See Also =
= Version Number =
To discover what Tor version is currently in use, run the following command inside {{project_name_gateway_short}} ([[Qubes|{{q_project_name_short}}]]: <code>{{project_name_gateway_vm}}</code>).


{{CodeSelect|code=
* [[Why_does_Whonix_use_Tor| Why does Whonix use Tor?]]
anon-info
* [[Why is Tor slow| Why is Tor slow?]]
}}
* [[Bridges| Censorship Circumvention - Tor Bridge Mode, using (private) (obfuscated) bridges]]
* [[Hide Tor and Whonix from your ISP| Hide the fact that you are using Tor/Whonix]]
* [[Tor Controller| Controlling Tor]]
* [[Onion Services| Hosting Tor Onion Services, ANY, Hidden Webserver]]
* [[Comparison Of Tor Proxies CGI proxies Proxy Chains And VPN Services|Comparison of Tor, Proxies, CGI proxies, Proxy Chains and VPN Services]]


The output should be similar to the following.


<pre>
= Advanced Topics =
INFO: version of the 'tor' package: 0.4.6.9-1~d11.bullseye+1
== Entry Guards ==
</pre>
=== Introduction ===


See also {{kicksecure_wiki
{{Persistent Tor Entry Guards Introduction}}
|wikipage=Tor_Versioning
|text=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.

{{CodeSelect|code=
sudo apt update
}}

'''3.''' Show available Tor versions.

{{CodeSelect|code=
apt list tor -a
}}

Alternatively you could also look up the version number available from [https://packages.debian.org/{{stable_project_version_based_on_Debian_codename}}
/tor Debian's <code>tor</code> package].

'''4.''' Downgrade for example to Tor version <code>0.4.7.16-1</code>.

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

{{CodeSelect|code=
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.


<ref>
<ref>
wiki editors note: These instructions are similar to {{kicksecure_wiki
As concluded in ticket [https://phabricator.whonix.org/T469 research non-persistent Tor directory guards], these are covered by the following instructions.
|wikipage=Tor_Versioning#Tor_Version_Downgrade
|text=Tor Version Downgrade
}}.
</ref>
</ref>


= Tor Consensus Re-Download =
=== Manual Rotation of Tor Guards ===
While this persists [[Tor Entry Guards]], it results in Tor re-downloading the Tor Consensus document. Should usually not be required.


{{CodeSelect|code=
{{mbox
sudo anon-consensus-del
| image = [[File:Ambox_warning_pn.svg.png|40px]]
| text = The decision to manually create and utilize a new Whonix-Gateway (sys-whonix) is risky and should not be taken undertaken lightly!
}}
}}


<ref>
[https://github.com/Kicksecure/helper-scripts/blob/master/usr/sbin/anon-consensus-del <code>anon-consensus-del</code>] (and its helper-script [https://github.com/Kicksecure/helper-scripts/blob/master/usr/sbin/anon-consensus-del-files <code>anon-consensus-del-files</code>]) is just a script to automate the following steps for better usability. It does in essence the following this:


{{CodeSelect|code=
On occasion, users may be tempted to create a new Whonix-Gateway ([[Qubes-Whonix]]: <code>sys-whonix</code>) because:
sudo systemctl stop tor@default
}}


{{CodeSelect|code=
* Bootstrapping is slow or regularly fails.
sudo su
* Tor logs show warnings suggesting evidence of route manipulation attacks or other oddities.
}}
* Logs reveal attempted attacks on Whonix or Tor processes, for example in AppArmor logs.
* Current Tor performance is very slow or unreliable due to collapsing circuits or other factors.
* The user is concerned about the amount of Tor data that could be revealed if the Whonix-Gateway is infected, particularly after a long period of use.


{{CodeSelect|code=
cd /var/lib/tor
}}


{{CodeSelect|code=
Creating a new Whonix-Gateway or sys-whonix will ''likely'' lead to a new set of Tor entry guards, which is [https://blog.torproject.org/improving-tors-anonymity-changing-guard-parameters proven to degrade anonymity]. Voluntary guard rotation via a new Whonix-Gateway is more dangerous than allowing "natural churn" as chosen by the Tor application for several reasons:
rm /var/lib/tor/cached-*
}}


{{CodeSelect|code=
* It increases the likelihood of a compromised or malicious Tor guard being selected, leading to a corresponding rise in the chance of a successful [https://securityaffairs.co/wordpress/17489/intelligence/traf%EF%AC%81c-correlation-vs-anonymity-on-tor.html correlation attack] if the adversary runs Tor exit relays in the network. <ref>Even if the adversary cannot enumerate all websites visited by the user, it might reveal sites visited more regularly, such as whonix.org</ref>
sudo systemctl restart tor@default
* The user is more likely to traverse a [http://freehaven.net/anonbib/#feamster:wpes2004 given] [http://freehaven.net/anonbib/#DBLP:conf:ccs:EdmanS09 set] of [http://freehaven.net/anonbib/#ndss13-relay-selection Internet infrastructure links] that are under the adversary's control, such as Autonomous Systems (ASes) or Internet Exchange Points (IXPs).
}}
* Every change of Tor guards acts like a fingerprinting mechanism, since other users are less likely to pick the same set. If the adversary is able to enumerate a user's Tor guards, and later observes someone with the same set, the chance is high the two observations stem from the same person. <ref>For example, the [https://trac.torproject.org/projects/tor/ticket/9273#comment:3 entropy associated with one, two or three guards] is 9, 17 and 25 bits, respectively.</ref>
</ref>


= Advanced Topics =
== Tuning ==
{{project_name_gateway_short}} can profit from RAM increase if a large number of circuits are created and Tor is kept busy. See [[RAM]] and [[Tuning]].


== Additional SocksPorts ==
For these reasons the Tor Project has changed its design and reduced the number of primary guard nodes to 3, and increased the set period for guard rotation. <ref>https://trac.torproject.org/projects/tor/ticket/8240</ref> The user should also contemplate the possibility their current poor Tor performance is an attempt by an advanced adversary to cause frustration, leading to a manual change in Tor guards: <ref>https://blog.torproject.org/improving-tors-anonymity-changing-guard-parameters</ref> <ref>For example if the current set of Tor guards is not under their control.</ref>
Various custom <code>SocksPorts</code> have already been prepared. Those are documented [[Stream_Isolation#How_to_mitigate_identity_correlation|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|Stream Isolation]] wiki page [[Stream Isolation#IsolateSOCKSAuth|(<code>IsolateSOCKSAuth</code>)]]. Otherwise:
<blockquote>We should also consider whether an adversary can *induce* congestion or resource exhaustion to cause a target user to switch away from her guard. Such an attack could work very nicely coupled with the guard enumeration attacks discussed above.</blockquote>


{{Community_Support|scope=chapter}}
In one sense, users should ''welcome'' slow entry guards, since "honeypot" operators on the Tor network are unlikely to have constrained bandwidth which might chase away intended targets. This thinking aligns with intelligence disclosures which deem all Tor users to be persons of interest to state-level adversaries.


Adding additional Tor <code>SocksPorts</code> to <code>/usr/local/etc/torrc.d/50_user.conf</code> is non-intuitive. <ref>
{{mbox
https://gitlab.torproject.org/legacy/trac/-/issues/15261
| image = [[File:Ambox_warning_pn.svg.png|40px]]
</ref>
| text = Users considering using disposable Whonix-Gateway ProxyVMs in Qubes R4 are [[Qubes/DisposableVM#Warning:_Avoid_Ephemeral_Whonix-Gateway_ProxyVMs_in_Qubes_R4|warned]] that this technique poses an even greater anonymity risk than described above; <b>new Tor guards are created during each distinct Whonix session.</b>

As noted in the Tor man page (<code>man tor</code>):

<blockquote>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 <u>all</u> 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.</blockquote>

Nick Mathewson from The Tor Project has also noted: <ref>
https://gitlab.torproject.org/legacy/trac/-/issues/15261#comment:1
</ref>

<blockquote>So to make sure that the SocksPort in the torrc does what you want, write it as <code>+SocksPort</code>.</blockquote>

{{Box|text=
<u>Tor configuration for additional <code>SocksPorts</code>s.</u>

'''1.''' [[Tor#Edit_Tor_Configuration|Edit Tor Configuration]]

'''2.''' Learn the syntax.

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

<pre>
+SocksPort 127.0.0.1:port-number
+SocksPort 10.152.152.10:port-number
</pre>

<code>port-number</code> will need to be replaced, which is documented below.

'''3.''' Add.

Here is an example that needs adjustment.

Notes:

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

{{CodeSelect|code=
+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 {{project_name_short}} firewall.
Under certain circumstances, users will feel compelled to proceed despite the anonymity risks. In this instance, it may be safer to first try: <ref>This issue requires further research.</ref>


{{Box|text=
* One of the fallback primary entry guards.
<u>Firewall configuration for additional <code>SocksPorts</code>s.</u>
* A configured [[Bridges|bridge]].
* Possibly [[Tunnels/Introduction|combine tunnels with Tor]].
* Creating a fresh Whonix-Gateway (sys-whonix), and copying across the Tor state file.


'''1.''' {{Firewall_Settings_Gateway}}


'''2.''' Learn the syntax.
The user can also persist with poor performance and wait for normal guard rotation. <ref>Note that if the problem relates to a dead entry guard(s), Tor is configured to eventually remove them.</ref> Users should note that [[tor#Fresh_Tor_Entry_Guards_by_regenerating_Tor_State_File|regenerating the Tor state file]] poses the same anonymity risks as outlined in this section.


Only need to read this. No need to copy anything.
=== Alternating Bridges ===
If you are using [[bridges|bridges]] already, use different bridges for different locations. Or if you are not a bridge user, you could consider to sometimes use alternate bridges in different locations and entry guards in your main location or so.


<pre>
On your Whonix-Gateway.
INTERNAL_OPEN_PORTS+=" port-number "
</pre>


<code>port-number</code> will need to be replaced, which is documented below.
1. {{Disable_Tor}}


'''3.''' Add setting.
2. Configure Tor to use bridges. Refer to the [[Bridges|Bridges]] documentation.


Notes:
3. Enable Tor using whonixsetup / whonix-setup-wizard at your new location.


* Replace port <code>9100</code> with the actual port for the additional <code>SocksPorts</code> you want to add.
4. Before you leave this location, disable Tor and add a different bridge address if going to a different place. To go back to your usual guard nodes at home, remove the torrc bridge settings before you enable the network or rollback to a vm snapshot you created there.


{{CodeSelect|code=
=== Fresh Tor Entry Guards by Regenerating the Tor State File ===
INTERNAL_OPEN_PORTS+=" 9100 "
Usually something to avoid unless you know what you are doing (see [[#Introduction|Introduction]]). This is a method you could use if you just once wanted to change your Tor entry guards, such as before you permanently relocate to a new location.
}}


'''4.''' Save.
On your Whonix-Gateway.


1. {{Disable_Tor}}
'''5.''' {{Reload_Firewall}}
}}


Platform specific notice:
2. Delete Tor's state file.

* [[Non-Qubes-Whonix]]: No special notice.
* [[Qubes-Whonix]]: Either a reboot <u>or</u> running <code>replace-ips</code> is required. <ref>
[https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-whonix/replace-ips <code>/usr/lib/qubes-whonix/replace-ips</code>] is a script that automatically run at boot time in Qubes-Whonix which replaces the hardcoded IP <code>10.152.152.10</code> with Qubes dynamic automatically assigned internal IP.
</ref>
** {{CodeSelect|code=
sudo /usr/lib/qubes-whonix/replace-ips
}}

Done.

The additional <code>SocksPort</code> should now be functional.

For troubleshooting, see footnote. <ref>
Show Tor listening ports on Whonix-Gateway. Note: replace <code>9100</code> by the actual port number.


{{CodeSelect|code=
{{CodeSelect|code=
sudo netstat -tulpen {{!}} grep 9100
sudo rm /var/lib/tor/state
}}
}}


Check if the <code>SocksPort</code> is reachable.
3. Enable Tor using whonixsetup / whonix-setup-wizard at your new location.


{{CodeSelect|code=
=== Always Non-Persistent Entry Guards ===
curl.anondist-orig --head $(qubesdb-read', '/qubes-netvm-gateway):9100
You could consider to always use non-persistent entry guards. In most cases, this is something to avoid because persistent entry guards is a security feature as explained in the [[#Introduction|introduction]]. A much more secure, but more time expensive approach would be [[#Alternating Bridges|Alternating Bridges]].
}}


* Whonix-Gateway localhost:
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
** {{CodeSelect|inline=true|code=
If you would like to see more information anyway, please press on expand on the right.
curl.anondist-orig --head 127.0.0.1:9100
<div class="mw-collapsible-content">
}}
On your Whonix-Gateway.
* Non-Qubes-Whonix-Gateway internal interface: {{CodeSelect|inline=true|code=
curl.anondist-orig --head 10.152.152.10:9100
}}
* Qubes-Whonix-Gateway internal interface: {{CodeSelect|inline=true|code=
curl.anondist-orig --head $(qubesdb-read /qubes-netvm-gateway):9100
}}


Expected output:
1. Adjust whonixcheck settings (applies until Whonix 12):


<pre>
{{Open with root rights|filename=
HTTP/1.0 501 Tor is not an HTTP Proxy
/etc/whonix.d/50_user.conf
</pre>

This means the port was reachable.

Or.

* Non-Qubes-Whonix-Workstation: {{CodeSelect|inline=true|code=
curl.anondist-orig --head 10.152.152.10:9100
}}
* Qubes-Whonix-Workstation: {{CodeSelect|inline=true|code=
curl.anondist-orig --head $(qubesdb-read /qubes-gateway):9100
}}
}}


Also useful.
Add.


{{CodeSelect|code=
{{CodeSelect|code=
sudo ifconfig
whonixcheck_skip_functions+=" check_tor_pid "
}}
}}
</ref>


{{Anchor|Blacklist Certain Onion Services from Connecting}}
Save.


== Multiple Tor Daemons ==
2. {{Disable_Tor}}
TODO: document


Mostly [[Unsupported|undocumented]].
3. Modify Tor settings.


Extra complexity in Qubes due to non-persistence of root file system in App Qube which is undocumented.
{{Open /etc/tor/torrc}}


[[Unsupported]]!
Add.

The textual string <code>extradaemon1</code> 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 <code>extradaemon2</code>.

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


{{CodeSelect|code=
{{CodeSelect|code=
sudo tor-instance-create "extradaemon1"
DataDirectory /var/run/tor
}}
}}


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


{{CodeSelect|code=
4. Enable Tor using whonixsetup / whonix-setup-wizard at your new location.
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.
5. Before you leave this location, disable Tor and repeat the above steps if going to a different place. To go back to your usual guard nodes at home, remove the torrc setting before you enable the network or rollback to a vm snapshot you created there.

{{CodeSelect|code=
sudo chown --recursive "_tor-extradaemon1:_tor-extradaemon1" "/var/lib/tor-instances/extradaemon1"
}}

Firewall settings change required. <ref>
On {{project_name_gateway_short}}, 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]].
</ref>

{{Box|text=
'''1.''' {{Firewall_Settings_Gateway}}

'''2.''' Add setting.

{{CodeSelect|code=
TOR_USER="$(id -u debian-tor) $(id -u _tor-extradaemon1)"
}}

'''3.''' Save.

'''4.''' {{Reload_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.

{{CodeSelect|code=
sudoedit /etc/tor/instances/extradaemon1/torrc
}}

Paste the following content. Example.

{{CodeSelect|code=
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

{{CodeSelect|code=
sudo systemctl enable "tor@extradaemon1.service"
}}

We start the new tor instance:

{{CodeSelect|code=
sudo systemctl restart "tor@extradaemon1.service"
}}

And we can check if the new instance is running

{{CodeSelect|code=
sudo systemctl status --no-block --no-pager "tor@extradaemon1.service"
}}

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

{{CodeSelect|code=
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.

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = This procedure is experimental. Testers only.
}}

'''1.''' {{Open /usr/local/etc/torrc.d/50_user.conf}}

'''2.''' Use the <code>MapAddress</code> configuration option.

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

Note: Replace <code>eixoaclv7qvnmu5rolbdwba65xpdiditdoyp6edsre3fitad777jr3ad.onion</code> with the actual onion service that should be blacklisted.

TODO: Replace <code>blackhole-address.tld</code> with an actual blackhole address.

{{CodeSelect|code=
MapAddress eixoaclv7qvnmu5rolbdwba65xpdiditdoyp6edsre3fitad777jr3ad.onion blackhole-address.tld
}}

'''3.''' {{Reload_Tor}}

'''4.''' Done.

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

== Entry Guards ==
{{Anchor|Manual Rotation of Tor Guards}}
{{Anchor|Security and Performance Related Issues}}
{{Anchor|Mitigate the Threat of Guard Fingerprinting}}
{{Anchor|Clone {{project_name_gateway_short}} ({{project_name_gateway_vm}}) with New Entry Guards}}
{{Anchor|Regenerate the Tor State After Saving the Tor State Folder}}
{{Anchor|Alternating Bridges}}
{{Anchor|Copy Tor State Files to Another {{project_name_gateway_vm}} Instance}}
{{Anchor|Fresh Tor Entry Guards by Regenerating the Tor State File}}
{{Anchor|Notes}}

This entry has been moved [[Tor_Entry_Guards|here]].

== Manual Bridge Configuration ==
It is recommended to first read the main [[Bridges]] article.

For the majority of users, the [[Anon_Connection_Wizard|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_/usr/local/etc/torrc.d/50_user.conf}}

=== Step 2: Edit Tor Configuration ===

==== Use obfs4 Bridges ====

<div class="toccolours mw-collapsible mw-collapsed">
<div class="mw-collapsible-content">
{{Box|text=
'''1.''' Open {{Code2|/usr/local/etc/torrc.d/50_user.conf}} in an editor.

Copy and paste the following text to enable the use of {{Code2|obfs4}} bridges. <ref>
{{Code2|obfs3}} bridges have been deprecated by upstream, The Tor Project in favor of {{Code2|obfs4}}.
</ref> <ref>
{{CodeSelect|code=
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
}}
</ref>

{{CodeSelect|code=
UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
}}

'''2.''' Add the bridge IP addresses that were sourced in the [[Bridges#Finding_a_Bridge_and_Choosing_the_Right_Protocol|Finding a Bridge and Choosing the Right Protocol]] section.

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

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = In the <i>obfs4</i> example below: <br />
* <u>Do not copy and paste this list of bridge entries to the {{Code2|50_user.conf}} file.</u> They will not work.
* Retrieve [https://bridges.torproject.org/bridges?transport=obfs4 obfs4 bridges] from The Tor Project <u>before</u> editing this file.
* <u>Capitalization in the {{Code2|50_user.conf}} file matters.</u> For example, bridges will not connect if users type "bridge" instead of "Bridge".
}}

{{Code2|Obfs4}} example text to add to {{Code2|/usr/local/etc/torrc.d/50_user.conf}}.

{{CodeSelect|code=
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 {{Code2|obfs4}} torrc file is below. Check your file is similar, except for the specific bridge entries.

<pre>
# 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
</pre>

<ref>
{{Code2|fte}} example text to add to {{Code2|/usr/local/etc/torrc.d/50_user.conf}}.

fte is supported in {{project_name_short}} 15, but further testing is required; see: https://phabricator.whonix.org/T520
{{CodeSelect|code=
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
Bridge fte 10.200.100.60:95128 4352e58420e68f5e40bf7c74faddccd9d1349413
Bridge fte 300.100.300.80:23521 4352e58420e68f5e40bf7c74faddccd9d1349413
}}
</ref>

'''3.''' After {{Code2|/usr/local/etc/torrc.d/50_user.conf}} editing is finished, save and exit.

<pre>
<Ctrl-X> --> press Y --> <Enter>
</pre>
}}
</div>
</div>
</div>
</div>


=== Notes ===
==== Use meek_lite Bridges ====


<div class="toccolours mw-collapsible mw-collapsed">
* The proposed Tails solutions towards AdvGoalTracking have disadvantages<ref>https://tails.boum.org/blueprint/persistent_Tor_state/</ref><ref>https://blog.torproject.org/blog/tor-weekly-news-%E2%80%94-june-17th-2015#A_persistent_Tor_state_for_Tails</ref> and are not options for Whonix because we don't connect directly to a user's internet LAN anyway, so trying to remember a network based on its SSID will not work. Unlike wireless access points, wired networks (physical or virtual) lack SSIDs and cannot be "remembered" that way.
<div class="mw-collapsible-content">
{{Code2|meek_lite}} bridges are available. To use them, simply add one more line to the {{Code2|/usr/local/etc/torrc.d/50_user.conf}} file. Take note the bridge type is called {{Code2|meek_lite}}, not {{Code2|meek}} which is used in Tor Browser Bundle. <ref>
{{Code2|meek_lite}} actually uses a different implementation of {{Code2|obfs4proxy}}. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3
</ref>
{{Box|text=
'''1.''' Open {{Code2|/usr/local/etc/torrc.d/50_user.conf}} in an editor.


Copy and paste the following text to enable {{Code2|meek_lite}} bridges.
* Even if it were possible, it is best to avoid letting adversaries influence guard changes in any way. Spoofing MAC addresses or SSIDs would trigger use of the other entry guard recorded for another "location profile". Also global networks have generic characteristics that cannot be differentiated from the point of view of a connecting device leading to the same guards being used on different networks.


{{CodeSelect|code=
* Developers/Auditors-only: Development discussion related to this documentation chapter: [https://phabricator.whonix.org/T94 research non-persistent entry guards]
UseBridges 1
ClientTransportPlugin meek_lite exec /usr/bin/obfs4proxy
}}


'''2.''' Add a {{Code2|meek_lite}} bridge to the configuration file.
== Blacklist Certain Onion Services from Connecting ==
'''Experimental'''


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

Example. Add to {{Code2|/etc/tor/torrc}}. Replace {{Code2|bbbbbb6qtmqg65g6.onion}} with the actual onion service you want to blacklist.


{{CodeSelect|code=
{{CodeSelect|code=
Bridge meek_lite 0.0.2.0:2 B9E7141C594AF25699E0079C1F0146F409495296 url=https://d2cly7j4zqgua7.cloudfront.net/ front=a0.awsstatic.com
MapAddress bbbbbb6qtmqg65g6.onion 127.0.0.1
}}
}}

'''3.''' After {{Code2|/usr/local/etc/torrc.d/50_user.conf}} editing is finished, save and exit.

<pre>
<Ctrl-X> --> press Y --> <Enter>
</pre>
}}
</div>
</div>

=== Step 3: Enable Tor ===

Follow this procedure if it has not been previously completed.

{{Enable_Tor}}

=== Step 4: Have {{Code2|/usr/local/etc/torrc.d/50_user.conf}} Changes Take Effect ===


{{Reload_Tor}}
{{Reload_Tor}}


== Additional SocksPorts ==
== Tor Functions ==
Adding additional Tor SocksPorts to /etc/tor/torrc is kinda non-intuitive. <ref>https://trac.torproject.org/projects/tor/ticket/15261</ref>


=== Disable Tor ===
Quote Tor man page.
{{Disable_Tor}}
<blockquote>
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.
</blockquote>


=== Reload Tor ===
<blockquote>
{{Reload_Tor}}
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.

</blockquote>
=== Restart Tor ===
{{Restart_Tor}}

== vanguards ==
See [[Vanguards]].

== UDP ==
{{Tor_UDP}}

== ICMP ==
Same as above.

== DNS ==
Similar to above.

= FAQ =

== {{project_name_short}} is Preventing Tor from Bootstrapping! ==

Refer to the related [[Why_is_Tor_slow#Whonix_has_Slowed_Tor_Connections_Dramatically.21|{{project_name_short}} 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 [[System_Requirements|minimum system requirements]] have been met for {{project_name_short}}.
* Confirm the accuracy of the VM clock with [[Sdwdate|sdwdate]].
* Remove any changes that were made to the {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>) torrc configuration, such as [[Bridges|bridges]], pluggable transports, [[{{project_name_gateway_short}}_Security|seccomp, connection padding]] and so on.
* Test Tor functionality on the host.
* In [[Qubes|{{q_project_name_short}}]], [[Install_Tor_Browser_Outside_of_Whonix#Moderate:_{{q_project_name_short}}|test Tor functionality in a non-{{project_name_short}} AppVM]].
* Increase the amount of RAM available to {{project_name_gateway_short}} (<code>{{project_name_gateway_vm}}</code>).
* Follow other [[Troubleshooting]] advice.

== Can I Speed Up Tor or the {{project_name_gateway_short}}? ==

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

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = '''Reminder:''' [[Self_Support_First_Policy|{{project_name_short}} Reliance on Debian (and Tor)]] - ''"{{project_name_short}} is not a stripped down version of Debian; anything possible in "vanilla" Debian GNU/Linux can be replicated in {{project_name_short}}."'' Tor configurations are not limited by using {{project_name_short}}.
}}

Those who already know how to configure Tor in this way on the command line in vanilla Debian can follow the same procedure in {{project_name_gateway_short}}. This is not an endorsement for making these manual Tor changes because it is not recommended by Tor developers and thus the {{project_name_short}} team. <ref>Deferring to their expertise on the possible adverse anonymity effects.</ref> This is also the reason there are no instructions in the {{project_name_short}} 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 {{project_name_gateway_short}}.

== Does {{project_name_short}} Modify Tor? ==

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = Tor is an anonymizer developed by The Tor Project. [[Tor Browser]] is a web browser {{tpo_link||developed by the Tor Project}} which is optimized for privacy. Please do not confuse {{Code2|Tor}} with {{Code2|Tor Browser}} when conversing about {{project_name_short}} topics.

For differences of Tor Browser by Tor Project compared to Tor Browser in {{project_name_short}} see [[Tor_Browser#Whonix_Tor_Browser_Differences|{{project_name_short}} Tor Browser Differences]].
}}

{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = {{project_name_short}} does <u>not </u> modify the Tor package itself.
}}

Although {{project_name_short}} does not modify Tor, the Tor configuration file ''has'' been adapted for {{project_name_short}}. To inspect the relevant files, check the following on {{project_name_gateway_short}}: <ref>Changes to the configuration file are made by the [https://github.com/{{project_name_short}}/anon-gw-anonymizer-config anon-gw-anonymizer-config] package.</ref>

* <code>/etc/tor/torrc</code> file.
* <code>/etc/torrc.d</code> folder.
* <code>/usr/local/etc/torrc.d/</code> folder.
* <code>/usr/share/tor/tor-service-defaults-torrc</code> file.

Tor is not patched and the normal Tor Debian package and [[vanguards]] is installed by default in {{project_name_short}}. ([[Dev/Tor#Tor_Version|technical details]])

Any changes to the Tor routing algorithm should be proposed, discussed and eventually implemented upstream in Tor on torproject.org. <ref>This means changes occur for all Tor users and not a subset relying on a particular distribution.</ref> If proposed changes are not adopted by The Tor Project, then the option to create a Tor fork <ref name=fork>
https://en.wikipedia.org/wiki/Fork_(software_development)
</ref> is available. Tor has already been forked at least once.

A general {{project_name_short}} 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 {{project_name_short}} discussions to the security impacts of the modified routing algorithm. For these reasons, the {{project_name_short}} team is strongly disinclined to make any direct changes to the Tor package.

== Can {{project_name_short}} Improve Tor? ==

As outlined in the [[Tor#Does_{{project_name_short}}_Modify_Tor?|previous section]], {{project_name_short}} will not implement any changes to Tor directly and any suggested improvements or bug fixes are proposed upstream on torproject.org. This has already [[Dev/Threat_Model#Design_Document,_Innovations,_and_Research|happened]] on occasion. Creating {{project_name_short}} 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 <ref name=fork /> it. Hypothetically, if a fork <ref name=fork /> developed a greater following than the original project due to proven security / anonymity benefits, then {{project_name_short}} would seriously consider making a switch.

== Tor Routing Algorithm ==
Quote Tor Project FAQ [https://2019.www.torproject.org/docs/faq.html.en#ChooseEntryExit Can I control which nodes (or country) are used for entry/exit?] (bold and underline added)


Quote Nick Mathewson <ref>https://trac.torproject.org/projects/tor/ticket/15261#comment:1</ref>:
<blockquote>
<blockquote>
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:
So to make sure that the SocksPort in the torrc does what you want, write it as <code>+SocksPort</code>.

[...]

'''We recommend you do <u>not</u> 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.
</blockquote>
</blockquote>


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:
After adding custom ports, you would also have to edit Whonix's firewall. But you are lucky, you don't need to do that. Various custom ports for such use cases have already been added.


* [https://www.freehaven.net/anonbib/ Anonymity Bibliography - Collection Anonymity Research]
Those are documented here:<br />
* Read the [https://blog.torproject.org Tor blog] as there are often blog posts discussing anonymity research such as blog post [https://blog.torproject.org/new-low-cost-traffic-analysis-attacks-mitigations new low cost traffic analysis attacks and mitigations].
[[Stream_Isolation#How_to_mitigate_identity_correlation]]


The following resources describe the organizational structure of the {{project_name_short}} project in relation to The Tor Project, Debian and other upstream sources.
= UDP =
{{Tor_UDP}}


* [[Dev/Relationship_With_Upstream|{{project_name_short}} Relationship With Upstream]]
= Reload Tor =
* [[Why_does_{{project_name_short}}_use_Tor|Why does {{project_name_short}} use Tor?]]
{{Reload_Tor}}
* [[Trust|Placing Trust in {{project_name_short}}]]
* [[Self_Support_First_Policy|Self Support First Policy]]
* {{kicksecure_wiki
|wikipage=Linux User Experience versus Commercial Operating Systems
|text=Linux User Experience versus Commercial Operating Systems
}}


See also:
= Restart Tor =
{{Restart_Tor}}


* [[#Does {{project_name_short}} Modify Tor?|Does {{project_name_short}} Modify Tor?]]
= Disable Tor =
* [[#Can {{project_name_short}} Improve Tor?|Can {{project_name_short}} Improve Tor?]]
{{Disable_Tor}}

== How do I Change Other Tor Settings? ==

Questions are often raised in forums about how other Tor-specific changes can be made in {{project_name_short}}, such as excluding specific exit nodes. <ref>
https://forums.whonix.org/t/how-to-set-an-exit-node-in-wonix-of-qubesos/9070
</ref>

In many cases, making such changes is already documented {{project_name_short}} [[Documentation]]. In other cases such changes are discouraged.

In all instances:

# Changes must be made to the Tor configuration file as per [[#Edit Tor Configuration|Edit Tor Configuration]].
# Refer to the [https://2019.www.torproject.org/docs/tor-manual.html.en 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:

[[#Tor Routing Algorithm|Discouraged!]]

<pre>
ExcludeExitNodes {us},{au},{ca},{nz},{gb}
StrictNodes 1
</pre>

A [[#Configuration Check|Configuration Check]] should be run afterwards inside {{project_name_gateway_short}} ([[Qubes|{{q_project_name_short}}]]: <code>{{project_name_gateway_vm}}</code>) to confirm there are no Tor configuration syntax errors. As these configurations are specific to Tor and [[unspecific|unspecific to {{project_name_short}})]], the [[Free_Support_Principle|Self Support First Policy]] applies.

== How do I Install the Latest Tor Version? ==

Follow the instructions [[Tor_Versioning|here]] to install later Tor versions from either:

* the {{project_name_short}} repository; or
* Tor Project APT repositories; or
* Tor Project source code.

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

* <code>anon-info</code> &rarr; [[#Version Number|Show Tor Version Number]]
* <code>anon-verify</code> &rarr; [[#Configuration Check|Tor Configuration Check]]
* <code>anon-log</code> &rarr; [[#anon-log|Tor Log Analysis]]

See also:

* [[Network Obstacle]]
* [[Bridges|Censorship Circumvention - Configure (Private) (Obfuscated) Tor Bridges]]

= Tor Generic Bug Reproduction =
Based on [[Reporting_Bugs#Bug_Report_Recommendations|Bug Report Recommendations]], specifically [[Reporting_Bugs#Generic_Bug_Reproduction|Generic Bug Reproduction]]. Similar to [[Troubleshooting]] advice "Try a non-Whonix VM".

The following results in a manual reproduction of the [[Dev/Tor|{{project_name_short}} Tor Integration]] without involving {{project_name_short}}. This enables the user to remove {{project_name_short}} as a possible source of issues and reduces the added complexity of {{project_name_short}}.

# Install Debian <code>{{Stable project version based on Debian codename}}</code> inside a VM.
# Install the <code>tor</code> Debian package.
{{box|text=
{{Install Package|package=tor}}
}}
# Skip vanguards steps depending on whether the [[vanguards]] wiki page states that it is currently used by {{project_name_short}} or not.
# Install [[vanguards]] from the Debian <code>{{Stable project version based on Debian codename}}</code> repository. If needed, see footnote for installation instructions. <ref>
{{Install Package|package=vanguards}}
</ref>
# Make vanguards work with Tor. [[Unspecific|Unspecific to {{project_name_short}}]]. See footnotes. <ref>
{{Box|text=
'''1.''' {{Open with root rights|
filename=/etc/tor/vanguards.conf
}}

'''2.''' change <code>control_socket = </code> to <code>control_socket = /run/tor/control</code>

'''3.''' Save.

'''4.''' Restart vanguards.

{{CodeSelect|code=
sudo systemctl restart vanguards
}}
}}
</ref> <ref>
https://github.com/mikeperry-tor/vanguards/issues/47
</ref>
# Attempt to reproduce the original issue.
# If the issue is reproducible without involving {{project_name_short}} then the issue is unspecific to {{project_name_short}}. This enables the user to utilize upstream (original authors of Tor software, Tor community) resources. [[Please_Use_Search_Engines_And_See_Documentation_First|Please use Search Engines and see Documentation First]]. If needed, submit an upstream support request or bug report. In this case, mentioning {{project_name_short}} is discouraged. Mentioning {{project_name_short}} even though it is an issue unspecific to {{project_name_short}} could add confusion. <ref>
The reader considering a {{project_name_short}} specific issue while there cannot be one.
</ref>

= Further Reading =
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[Why_does_{{project_name_short}}_use_Tor|Why does {{project_name_short}} use Tor?]]
* [[Why is Tor slow|Why is Tor slow?]]
* [[Bridges|Censorship Circumvention - Configure (Private) (Obfuscated) Tor Bridges]]
* [[Anon_Connection_Wizard|Anon Connection Wizard]]
* [[Network Obstacle]]
* [[Hide Tor from your Internet Service Provider|Hide Tor and {{project_name_short}} use from the ISP]]
* [[Tor Controller|Tor Controller - Control and Monitor Tor]]
* [[Onion Services|Hosting Tor Onion Services (<u>any</u> Hidden Webserver)]]
* [[Comparison Of Tor Proxies CGI proxies Proxy Chains And VPN Services|Comparison of Tor with CGI Proxies, Proxy Chains and VPN Services]]
* [[Tor_Versioning|Newer Tor Versions]]
* [[Tor-ctrl-observer|tor-ctrl-observer - Tor Connection Destination Viewer]]
</div>


= Footnotes / References =
= Footnotes / References =
{{reflist|close=1}}
<references />


{{Footer}}
{{Footer}}

Latest revision as of 05:54, 6 March 2024

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 editorarchive.org 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://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[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://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[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 systemcheckarchive.org 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:

Quotearchive.org 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 it is reported that Tor is not running (such as by systemcheckarchive.org 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[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 systemcheckarchive.org, 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 systemcheckarchive.org'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 Kicksecure logo Newer Tor Versions The Web Archive Onion Version .

Tor Version Downgrade[edit]

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/bookwormarchive.org /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.

[7]

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

[8]

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:

Info 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. [9]

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

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 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_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-17Whonix 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. 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 MenuApplicationsSystemReload Whonix Firewall

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

Platform specific notice:

Done.

The additional SocksPort should now be functional.

For troubleshooting, see footnote. [12]

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.

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

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_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-17Whonix 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.

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/14124archive.org

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

Info This procedure is experimental. Testers only.

1. Open file /usr/local/etc/torrc.d/50_user.conf in a text editorarchive.org 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.

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

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

[16]

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

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

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

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]

The Tor software does not support UDP. The feature request UDP over Torarchive.org was created in 2013 and closed as won't fixarchive.org 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.

DNS[edit]

Similar to 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. [20] 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 The Web Archive Onion Version 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: [21]

  • /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. [22] If proposed changes are not adopted by The Tor Project, then the option to create a Tor fork [23] 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 [23] it. Hypothetically, if a fork [23] 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?archive.org (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. [24]

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

Install package(s) tor.

A. Update the package lists and upgrade the systemarchive.org.

sudo apt update && sudo apt full-upgrade

B. Install the tor package(s).

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

sudo apt install --no-install-recommends tor

C. 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. [25]
  3. Make vanguards work with Tor. Unspecific to Whonix. See footnotes. [26] [27]
  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. [28]

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 directoryarchive.org
    • -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 permissionarchive.org
  5. UWT_DEV_PASSTHROUGH=1 curl 10.152.152.10:9100
  6. wiki editors note: These instructions are similar to Kicksecure logo Tor Version Downgrade The Web Archive Onion Version .
  7. anon-consensus-delarchive.org (and its helper-script anon-consensus-del-filesarchive.org) 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
  8. https://gitlab.torproject.org/legacy/trac/-/issues/15261archive.org
  9. https://gitlab.torproject.org/legacy/trac/-/issues/15261#comment:1archive.org
  10. /usr/lib/qubes-whonix/replace-ipsarchive.org is a script that automatically run at boot time in Qubes-Whonix which replaces the hardcoded IP 10.152.152.10 with Qubes dynamic automatically assigned internal IP.
  11. Show Tor listening ports on Whonix-Gateway. Note: replace 9100 by the actual port number. sudo netstat -tulpen | grep 9100 Check if the SocksPort is reachable. curl.anondist-orig --head $(qubesdb-read', '/qubes-netvm-gateway):9100
    • Whonix-Gateway localhost:
      • curl.anondist-orig --head 127.0.0.1:9100
    • Non-Qubes-Whonix-Gateway internal interface: curl.anondist-orig --head 10.152.152.10:9100
    • Qubes-Whonix-Gateway internal interface: curl.anondist-orig --head $(qubesdb-read /qubes-netvm-gateway):9100
    Expected output:
    HTTP/1.0 501 Tor is not an HTTP Proxy
    

    This means the port was reachable.

    Or.

    • Non-Qubes-Whonix-Workstation: curl.anondist-orig --head 10.152.152.10:9100
    • Qubes-Whonix-Workstation: curl.anondist-orig --head $(qubesdb-read /qubes-gateway):9100

    Also useful.

    sudo ifconfig

  12. 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.
  13. obfs3 bridges have been deprecated by upstream, The Tor Project in favor of obfs4.
  14. ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
  15. 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/T520archive.org ClientTransportPlugin fte exec /usr/bin/fteproxy --managed Bridge fte 10.200.100.60:95128 4352e58420e68f5e40bf7c74faddccd9d1349413 Bridge fte 300.100.300.80:23521 4352e58420e68f5e40bf7c74faddccd9d1349413
  16. meek_lite actually uses a different implementation of obfs4proxy. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3archive.org
  17. Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support yet.archive.org It is therefore unavailable on Whonix-Gateway CLI. Use setup-dist instead; note that functionality is limited and does not support Bridges.
  18. Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support yet.archive.org It is therefore unavailable on Whonix-Gateway CLI. Use setup-dist instead; note that functionality is limited and does not support Bridges.
  19. Deferring to their expertise on the possible adverse anonymity effects.
  20. Changes to the configuration file are made by the anon-gw-anonymizer-configarchive.org package.
  21. This means changes occur for all Tor users and not a subset relying on a particular distribution.
  22. 23.0 23.1 23.2 https://en.wikipedia.org/wiki/Fork_(software_development)archive.org
  23. https://forums.whonix.org/t/how-to-set-an-exit-node-in-wonix-of-qubesos/9070archive.org
  24. Install package(s) vanguards.

    A. Update the package lists and upgrade the systemarchive.org.

    sudo apt update && sudo apt full-upgrade

    B. Install the vanguards package(s).

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

    sudo apt install --no-install-recommends vanguards

    C. Done.

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

  25. 1. Open file /etc/tor/vanguards.conf in an editor with root rights.

    Non-Qubes-Whonix

    This box uses sudoedit for better security.

    Qubes-Whonix

    NOTE: When using Qubes-Whonix, this needs to be done inside the Template.

    Others and Alternatives

    • This is just an example. Other tools could 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

  26. https://github.com/mikeperry-tor/vanguards/issues/47archive.org
  27. The reader considering a Whonix specific issue while there cannot be one.

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!