/usr/local/etc/torrc.d/40_tor_control_panel.conf.
Advanced Tor Configuration:
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 all unique user Tor configurations should be stored in Tor configuration file /usr/local/etc/torrc.d/50_user.conf and nowhere else.
/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.
Note that {{project_name_short}} 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_Files#Configuration_Drop-In_Folders|Configuration Drop-In Folders]] /etc/torrc.d/ and /usr/local/etc/torrc.d/ 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.
Debian feature request: [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=866187 add torrc.d configuration directory]
== Edit Tor Configuration ==
{{Open /usr/local/etc/torrc.d/50 user.conf}}
== Configuration Check ==
To discover if there are any Tor configuration syntax errors and to see which Tor configuration files are processed in which order, run the following command inside {{project_name_gateway_long}} ([[Qubes|{{q_project_name_long}}]]: {{project_name_gateway_vm}}).
{{CodeSelect|code=
anon-verify
}}
The output should be similar to the following.
/===================================================================\ | Report Summary | \===================================================================/ No error detected in your Tor configuration. Tor verify exit code: 0 /===================================================================\ | Tor Full Report | \===================================================================/ Aug 09 19:29:56.669 [notice] Tor 0.3.3.9 (git-ca1a436fa8e53a32) running on Linux with Libevent 2.0.21-stable, OpenSSL 1.1.0f, Zlib 1.2.8, Liblzma 5.2.2, and Libzstd 1.1.2. Aug 09 19:29:56.669 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://archive.ph/o/Aj1oi/https://www.torproject.org/download/download%23warning Aug 09 19:29:56.669 [notice] Read configuration file "/usr/share/tor/tor-service-defaults-torrc". Aug 09 19:29:56.669 [notice] Read configuration file "/etc/tor/torrc". Aug 09 19:29:56.672 [notice] You configured a non-loopback address '10.137.8.1:5300' for DNSPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. Aug 09 19:29:56.672 [notice] You configured a non-loopback address '10.137.8.1:9040' for TransPort. This allows everybody on your local network to use your machine as a proxy. Make sure this is what you wanted. Configuration was valid /===================================================================\ | Used Tor Configuration Files | \===================================================================/ 5 files are used as Tor configuration files: /usr/share/tor/tor-service-defaults-torrc /etc/tor/torrc /etc/torrc.d/95_whonix.conf /usr/local/etc/torrc.d/40_tor_control_panel.conf /usr/local/etc/torrc.d/50_user.conf ====================================================================== Log Analysis = == Introduction == Analysis of Tor's (and [[vanguards|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 ==
anon-log simplifies the manual [[#Dump Tor Log|dump Tor log]] command by only showing relevant log entries and no [[#Non-Issues|non-issues]].
{{CodeSelect|code=
sudo anon-log
}}
The output should be similar to the following.
tor.service: Starting Anonymizing overlay network for TCP (multi-instance-master)... Started Anonymizing overlay network for TCP (multi-instance-master). /run/tor/log: Jan 20 11:50:47.733 [notice] Tor 0.4.4.6 running on Linux with Libevent 2.1.8-stable, OpenSSL 1.1.1d, Zlib 1.2.11, Liblzma 5.2.4, and Libzstd 1.3.8. Jan 20 11:50:47.733 [notice] Tor can't help you if you use it wrong! Learn how to be safe at https://archive.ph/o/Aj1oi/https://www.torproject.org/download/download%23warning Jan 20 11:50:47.000 [notice] Bootstrapped 0% (starting): Starting Jan 20 11:50:48.000 [notice] Starting with guard context "default" Jan 20 11:50:48.000 [notice] Signaled readiness to systemd Jan 20 11:50:48.000 [notice] Received reload signal (hup). Reloading config and resetting internal state. Jan 20 11:50:48.000 [notice] Bootstrapped 5% (conn): Connecting to a relay Jan 20 11:50:48.000 [notice] Bootstrapped 10% (conn_done): Connected to a relay Jan 20 11:50:49.000 [notice] Bootstrapped 14% (handshake): Handshaking with a relay Jan 20 11:50:49.000 [notice] Bootstrapped 15% (handshake_done): Handshake with a relay done Jan 20 11:50:49.000 [notice] Bootstrapped 75% (enough_dirinfo): Loaded enough directory info to build circuits Jan 20 11:50:49.000 [notice] Bootstrapped 90% (ap_handshake_done): Handshake finished with a relay to build circuits Jan 20 11:50:49.000 [notice] Bootstrapped 95% (circuit_create): Establishing a Tor circuit Jan 20 11:50:54.000 [notice] Bootstrapped 100% (done): Done vanguards.service: WARNING[Wed Jan 20 11:50:48 2021]: Tor daemon connection closed. Trying again... NOTICE[Wed Jan 20 11:50:49 2021]: Vanguards 0.3.1 connected to Tor 0.4.4.6 using stem 1.7.1== Dump Tor Log == Not required when using [[#anon-log|anon-log]]. *
-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|vanguards]]
{{CodeSelect|code=
sudo journalctl -b --output cat --no-pager -u tor -u tor@default -u vanguards
}}
== Watch Tor Log ==
Users can also watch Tor's log as it is written.
{{CodeSelect|code=
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|reload Tor]], run the following command.
{{CodeSelect|code=
sudo service tor@default reload
}}
To [[#Restart Tor|restart Tor]], run the following command.
{{CodeSelect|code=
sudo service tor@default restart
}}
= Connectivity Troubleshooting =
To debug, try these commands in {{project_name_gateway_short}} ([[Qubes|{{q_project_name_short}}]]: {{project_name_gateway_vm}}).
{{Box|text=
'''1.''' See [[Troubleshooting]].
'''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 ping.]]
'''8.''' Sometimes a [[#Tor Consensus Re-Download|Tor Consensus Re-Download]] can help.
'''9.''' [[Tor#Log_Analysis|Tor Log Analysis]].
'''10.''' [...] 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 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]
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 {{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.
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. {{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. [https://phabricator.whonix.org/T855 systemcheck /var/lib/tor folder permission] }} = Non-Issues = {| class="wikitable" style="background-color: #fff;text-align: left" ! '''Message / Question''' ! '''Answer''' |- | {{Code2|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. |- | {{Code2|[WARN] Socks version 71 not recognized. (Tor is not an http proxy.)}} | 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. {{CodeSelect|code= {{Curl_Plain}} 10.152.152.10:9100 }} No warnings appear if the function works correctly. |- | {{Code2|[warn] Socks version 71 not recognized. (This port is not an HTTP proxy; did you want to use HTTPTunnelPort?)}} | Similar to above. |- | {{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. | 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}} (
{{project_name_gateway_vm}}) that is only available to {{project_name_workstation_long}} because {{project_name_gateway_short}} ({{project_name_gateway_vm}}) is firewalled. See ''{{W_Firewall}}'' or the {{project_name_short}} source code for further information.
|-
| {{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]].
|}
= 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}}]]: {{project_name_gateway_vm}}).
{{CodeSelect|code=
anon-info
}}
The output should be similar to the following.
INFO: version of the 'tor' package: 0.4.6.9-1~d11.bullseye+1See also {{kicksecure_wiki |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
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.
{{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.
wiki editors note: These instructions are similar to {{kicksecure_wiki
|wikipage=Tor_Versioning#Tor_Version_Downgrade
|text=Tor Version Downgrade
}}.
= Tor Consensus Re-Download =
While this persists [[Tor Entry Guards]], it results in Tor re-downloading the Tor Consensus document. Should usually not be required.
{{CodeSelect|code=
sudo anon-consensus-del
}}
[https://github.com/Kicksecure/helper-scripts/blob/master/usr/sbin/anon-consensus-del anon-consensus-del] (and its helper-script [https://github.com/Kicksecure/helper-scripts/blob/master/usr/sbin/anon-consensus-del-files anon-consensus-del-files]) is just a script to automate the following steps for better usability. It does in essence the following this:
{{CodeSelect|code=
sudo systemctl stop tor@default
}}
{{CodeSelect|code=
sudo su
}}
{{CodeSelect|code=
cd /var/lib/tor
}}
{{CodeSelect|code=
rm /var/lib/tor/cached-*
}}
{{CodeSelect|code=
sudo systemctl restart tor@default
}}
= 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 ==
Various custom SocksPorts 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|(IsolateSOCKSAuth)]]. Otherwise:
{{Community_Support|scope=chapter}}
Adding additional Tor SocksPorts to /usr/local/etc/torrc.d/50_user.conf is non-intuitive.
https://gitlab.torproject.org/legacy/trac/-/issues/15261
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: https://gitlab.torproject.org/legacy/trac/-/issues/15261#comment:1
So to make sure that the SocksPort in the torrc does what you want, write it as +SocksPort.
{{Box|text=
Tor configuration for additional SocksPortss.
'''1.''' [[Tor#Edit_Tor_Configuration|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.
{{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.
{{Box|text=
Firewall configuration for additional SocksPortss.
'''1.''' {{Firewall_Settings_Gateway}}
'''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.
{{CodeSelect|code=
INTERNAL_OPEN_PORTS+=" 9100 "
}}
'''4.''' Save.
'''5.''' {{Reload_Firewall}}
}}
Platform specific notice:
* [[Non-Qubes-Whonix]]: No special notice.
* [[Qubes-Whonix]]: Either a reboot or running replace-ips is required.
[https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-whonix/replace-ips /usr/lib/qubes-whonix/replace-ips] 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.
** {{CodeSelect|code=
sudo /usr/lib/qubes-whonix/replace-ips
}}
Done.
The additional SocksPort should now be functional.
For troubleshooting, see footnote.
Show Tor listening ports on Whonix-Gateway. Note: replace 9100 by the actual port number.
{{CodeSelect|code=
sudo netstat -tulpen {{!}} grep 9100
}}
Check if the SocksPort is reachable.
{{CodeSelect|code=
curl.anondist-orig --head $(qubesdb-read', '/qubes-netvm-gateway):9100
}}
* Whonix-Gateway localhost:
** {{CodeSelect|inline=true|code=
curl.anondist-orig --head 127.0.0.1:9100
}}
* 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:
HTTP/1.0 501 Tor is not an HTTP ProxyThis 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. {{CodeSelect|code= sudo ifconfig }} {{Anchor|Blacklist Certain Onion Services from Connecting}} == Multiple Tor Daemons == TODO: document Mostly [[Unsupported|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.
{{CodeSelect|code=
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.
{{CodeSelect|code=
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.
{{CodeSelect|code=
sudo chown --recursive "_tor-extradaemon1:_tor-extradaemon1" "/var/lib/tor-instances/extradaemon1"
}}
Firewall settings change required.
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]].
{{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 /var/lib/tor-instances/extradaemon1 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 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.
{{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 ====
# 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
{{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
}}
'''3.''' After {{Code2|/usr/local/etc/torrc.d/50_user.conf}} editing is finished, save and exit.
}}--> press Y -->
}}--> press Y -->
{{project_name_gateway_vm}}) 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}} ({{project_name_gateway_vm}}).
* 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. Deferring to their expertise on the possible adverse anonymity effects. 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 not 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}}: Changes to the configuration file are made by the [https://github.com/{{project_name_short}}/anon-gw-anonymizer-config anon-gw-anonymizer-config] package.
* /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 {{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. This means changes occur for all Tor users and not a subset relying on a particular distribution. If proposed changes are not adopted by The Tor Project, then the option to create a Tor fork
https://en.wikipedia.org/wiki/Fork_(software_development)
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 it. Hypothetically, if a 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)
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: * [https://www.freehaven.net/anonbib/ Anonymity Bibliography - Collection Anonymity Research] * 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]. The following resources describe the organizational structure of the {{project_name_short}} project in relation to The Tor Project, Debian and other upstream sources. * [[Dev/Relationship_With_Upstream|{{project_name_short}} Relationship With Upstream]] * [[Why_does_{{project_name_short}}_use_Tor|Why does {{project_name_short}} use 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: * [[#Does {{project_name_short}} Modify Tor?|Does {{project_name_short}} Modify Tor?]] * [[#Can {{project_name_short}} Improve Tor?|Can {{project_name_short}} Improve Tor?]] == How do I Change Other Tor Settings? == Questions are often raised in forums about how other Tor-specific changes can be made in {{project_name_short}}, such as excluding specific exit nodes. https://forums.whonix.org/t/how-to-set-an-exit-node-in-wonix-of-qubesos/9070 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!]]
ExcludeExitNodes {us},{au},{ca},{nz},{gb}
StrictNodes 1
A [[#Configuration Check|Configuration Check]] should be run afterwards inside {{project_name_gateway_short}} ([[Qubes|{{q_project_name_short}}]]: {{project_name_gateway_vm}}) 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.
* anon-info → [[#Version Number|Show Tor Version Number]]
* anon-verify → [[#Configuration Check|Tor Configuration Check]]
* anon-log → [[#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 {{Stable project version based on Debian codename}} inside a VM.
# Install the tor 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 {{Stable project version based on Debian codename}} repository. If needed, see footnote for installation instructions.
{{Install Package|package=vanguards}}
# Make vanguards work with Tor. [[Unspecific|Unspecific to {{project_name_short}}]]. See footnotes.
{{Box|text=
'''1.''' {{Open with root rights|
filename=/etc/tor/vanguards.conf
}}
'''2.''' change control_socket = to control_socket = /run/tor/control
'''3.''' Save.
'''4.''' Restart vanguards.
{{CodeSelect|code=
sudo systemctl restart vanguards
}}
}}
https://github.com/mikeperry-tor/vanguards/issues/47
# 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.
The reader considering a {{project_name_short}} specific issue while there cannot be one.
= Further Reading =