Connecting to a Proxy before Tor

From Whonix
Jump to navigation Jump to search

Instructions on how to connect to a proxy before Tor.



Before combining Tor with other tunnels, be sure to read and understand the risks!

Too difficult? Consider purchasing Premium Support.

Proxy Warning[edit]

Whonix first time users warning Warning! Take careful note of the following issues when using standard, common http(s)/SOCKS4(a)/5 proxies -- anonymizers that only use http(s)/SOCKS4(a)/5 as an interface [1] are exempt.

  • Most problems with these proxies are not caused by Whonix.
  • Connections to proxies are unencrypted and therefore should not be used to hide Tor use. This is because proxies are a type of tunnel-link which are not VPNs or SSH. Despite being unsuitable for hiding Tor due to the lack of encryption, in certain circumstances proxies might still be useful for users to circumvent censorship.
  • If state-level censorship of the Tor network must be circumvented, then a better solution may be Bridges or other alternative circumvention tools. [2]
  • Be especially careful with http(s) proxies. Some of them send the X-Forwarded-For header which discloses the IP address. http(s) proxies that do not send this header are sometimes called "elite" or "anonymous" proxies.
  • When using X-Forwarded-For http(s) proxies, Tor entry guards and Tor bridges can determine the IP address.
  • The unencrypted nature of proxies makes them unsuitable to hide Tor from destination websites. For simple IP logging / IP detection they might work unless they’re http(s) proxies and send the X-Forwarded-For header.

For further detailed information on proxies, see: Tor vs. Proxies, Proxy Chains.

Proxy Configuration Prerequisites[edit]

Info Tip: In order to configure a proxy, three things must be known in advance:

  1. where the proxy is running;
  2. the IP and port of the proxy; and
  3. what type of proxy is being used.

Location of the Running Proxy[edit]

The location of the running proxy is variable and depends on the user's system. Refer to the following resources for examples:

  • A) Proxy software might run on a remote computer, which is easier to set up.
  • B) Proxy software (such as Lantern) create a proxy tunnel on the local computer.
    • Qubes-Whonix VM: Lantern as an example.
    • Non-Qubes-Whonix VM: This is not yet fully documented, please contribute.
      • The proxy software must run either:
        • B1) Whonix-Gateway under the Linux user account tunnel; or
        • B2) on the host operating system (OS) (outside any virtual machine (VM)); or
        • B3) in another VM.
      • All of this is undocumented.
        • how to autostart custom software after reboot (systemd etc.)
        • custom proxy software setup example.

The Proxy IP and Port[edit]

Info If the proxy IP address and port is known, this section can be skipped.

  • If custom proxy software will be run on Whonix-Gateway, then this configuration is also called localhost. Usually the proxy IP address is
  • Note: It is necessary to use the IP address instead of the hostname ( If the proxy IP address is unknown, then in a terminal on the host operating system (OS) (outside of any virtual machine (VM)), run (Linux) nslookup; replace with the hostname of your actual proxy. Using the IP address instead of hostname might cause subtle fingerprinting issues -- see the footnote [3] for more information.

Type of Proxy in Use[edit]

It is necessary to know the proxy type from the following list:

  • HTTPProxy
  • HTTPSProxy
  • Socks4Proxy
  • Socks5Proxy

Also check whether the proxy requires a username and/or password beforehand.

Configure Whonix-Gateway[edit]


Tor natively supports proxy settings and only requires editing of the torrc file.

Option 1: Use Anon Connection Wizard[edit]

A proxy can be configured easily using Anon Connection Wizard.

Step 1: Start Anon Connection Wizard[edit]

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

Step 2: Use Proxy Configuration Page[edit]

Select "Use proxy before connecting to the Tor network" on the Proxy Configuration pageChoose the proxy typeFill out other necessary information

Info Tips: 1. Proxy Type

The proxy type is the protocol which is used to communicate with the proxy server. Since there are only three options, they can all be tried until one works.

2. Proxy IP/hostname

It is necessary to know the proxy IP for attempted connections. If the user is trying to connect to a local proxy, then should be specified since it is the localhost.

3. Proxy Port number

It is necessary to know the port number for attempted connections. It should be a positive integer from 1 to 65535. If searching for the listening port number of a well-known censorship circumvention tool, it can be found online.

4. Username and Password If the username and password are unknown, they should be left blank to see if the connection will succeed. In most cases they are not needed.

Option 2: Manually Configure Proxy[edit]

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

Depending on your proxy configuration, add the necessary settings to the /usr/local/etc/torrc.d/50_user.conf file. For more information on these settings, refer to the Tor (.oniononion) and read the

HTTPProxy host[:port]
HTTPProxyAuthenticator username:password
HTTPSProxy host[:port]
HTTPSProxyAuthenticator username:password

Socks4Proxy host[:port]

Socks5Proxy host[:port]
Socks5ProxyUsername username
Socks5ProxyPassword password

FascistFirewall 0|1

ReachableAddresses ADDR[/MASK][:PORT]…
ReachableDirAddresses ADDR[/MASK][:PORT]…
ReachableORAddresses ADDR[/MASK][:PORT]…

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. Optional: Test the configuration by running systemcheck.

The procedure is complete.


  1. Like the Tor, or I2P software.
  2. Users in China are unlikely to circumvent government with vanilla bridges, as they are uniformly blocked. That said, Anon Connection Wizard configured with the meek-amazon or meek-azure pluggable transport was reported to bypass Chinese censorship in late 2017. Unfortunately the meek-amazon pluggable transport was deprecated in after Amazon removed the domain fronting option.
  4. Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support It is therefore unavailable on Whonix-Gateway CLI. Use setup-dist instead; note that functionality is limited and does not support Bridges.

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!