Connecting to Tor before a VPN

From Whonix
Jump to navigation Jump to search

Instructions on how to connect to Tor before a VPN.

UserTorVPNInternet

Introduction[edit]

Whonix users have the option to use a VPN but in most cases it's not needed and there are other alternatives. Reading the Tunnels/Introduction wiki page beforehand is advice to learn more if using a VPN with Whonix is useful or harmful.

By design, a VPN routes all your applications -- those without any proxy settings -- through the VPN. This may be undesirable as explained below; for example, it increases the threat of identity correlation. To circumvent this possibility, only use this Whonix-Workstation for particular applications that should be routed through the tunnel-link. Refer to the Multiple Whonix-Workstation wiki chapter for further instructions.

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

Security Precautions[edit]

Prevent Bypassing of the Tunnel-Link[edit]


  • Apply the instructions Prevent Bypassing the Tunnel-Link to avoid unexpected results such as broken connectivity and/or traffic bypassing the tunnel-link and traffic only going through Tor.
    • Qubes-Whonix exception: There is one tunnel configuration where Qubes-Whonix users are better placed. When a separate tunnel-link VM is used between anon-whonix and sys-whonix (anon-whonixTunnel-linksys-whonix), these connections will fail without the following modifications.

Introduction

Disabling stream isolation will prevent bypassing of the tunnel-link. By default, many pre-installed applications are configured for Stream Isolation in Whonix. These specific applications are configured to use Tor SocksPorts, instead of Tor's TransPort.

All applications which are configured to use a Tor SocksPorts are not tunneled through the tunnel-link, but instead they are only tunneled through Tor. The reason is the following configuration does not touch local connections to 10.152.152.10, which is the Whonix-Gateway. Therefore, all Tor Browser proxy settings must be removed if attempting to tunnel Tor Browser via the route UserTorTunnel-linkInternet (or similar); see below for instructions.

Deactivate uwt Wrappers

The following instructions permanently deactivate all uwt wrappers and remove stream isolation for uwt-wrapped applications system-wide. Consequently, all uwt-wrapped applications revert to the default system networking configuration.

For more granular control of uwt wrapper deactivation, see: Deactivate uwt Stream Isolation Wrapper.

1. Platform specific notice:

2. Open file /etc/uwt.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/uwt.d/50_user.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/uwt.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/uwt.d/50_user.conf

3. Add.

uwtwrapper_global="0"

4. Save and exit.

5. Check that the changes have taken effect. Run in terminal: uwt_settings_show

It should print

uwt INFO: disabled.

6. Done.


Tor Browser Remove Proxy Settings

Introduction

This configuration results in Tor Browser no longer using proxy settings. With no proxy set, Tor Browser uses the (VM) system's default networking. This is identical to any other application inside Whonix-Workstation that has not been explicitly configured to use Tor via socks proxy settings or a socksifier. This setting is also called transparent torification. [2] [3]

info Why is this difficult?

This is difficult and may not work for you.

To learn why this is difficult, please press on Expand on the right.

Tor Browser, which is developed by upstream, The Tor Project (TPO), an independent entity has hard configured to use Tor as a proxy.

  • Upstream does not support user using Tor Browser with an additional extra proxy at the end of the chain, i.e.: userTorproxydestination
  • Upstream does also not support using Tor Browser with a proxy other than Tor, i.e.: usercustom proxydestination. This may or may not currently be possible but upstream does not provide documentation on how to do this.
  • Upstream does also not support using Tor Browser with a VPN instead of Tor, i.e. userVPNdestination.
  • Upstream does also not support using Tor Browser with a VPN in addition before Tor, i.e. userTorVPNdestination.

That makes sense from TPO's perspective as a project that maintains a browser that should always connect using the Tor network. Due to that perspective, proxy settings have been removed from Tor Browser to avoid user confusion and accidental misconfiguration. Little attention is spend on custom proxy settings. That, from TPO's perspective is assumed to only make sense for users using a Tor transparent proxy and that are already running Tor on a different computer in their LAN. Only a minority of users is using such configurations.

Because of this organisational and technical background, the highly specialized use case of configuring Tor Browser running inside Whonix-Workstation to use an additional proxy (user -> Tor -> proxy -> destination) is difficult to accomplish.

To learn more about this organisational and technical background see also Kicksecure logo Linux User Experience versus Commercial Operating Systems Onion Version

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.

Note: This action will break both Stream Isolation for Tor Browser and Tor Browser's SOCKS username for a request based on first party domainarchive.org feature. This worsens the web fingerprint and leads to pseudonymous (not anonymous) connections. To mitigate these risks, consider using More than one Tor Browser in Whonix, or preferably Multiple Whonix-Workstation.

Local socks proxy Method

This method works for removal of proxy settings but is rather lengthy and complicated. In case the user wants to have a look anyhow, please press on Expand on the right.

Since other methods to configure Tor Browser to use system default networking are broken due to Tor Browser changes by upstream, this new local socks proxy method stops anon-ws-disable-stacked-tor local port 9150 redirection to Whonix-Gateway 9150 (where a Tor SocksPort is listening). As a replacement, a local socks proxy listens on Whonix-Workstation local port 9150 which then forwards the traffic using system default networking. In result, if the user is using a VPN inside Whonix-Workstation or in a VPN-Gateway wretched between Whonix-Gateway and Whonix-Workstation, Tor Browser would use the VPN.

In this documentation, Dante is used as a local socks proxy. Development notes are kept on Dev/Dante.

1. Legacy notices.

  • New users, that did not apply instructions from this page again: No special notice.
  • Existing users: See below.

A few settings need to be undone.

  • A) Previous changes to /etc/environment as documented previously for other methods need to be undone.
  • B) Tor Browser needs to be re-installed. This is because undoing the previous configuration is difficult and undocumented.

2. Stop default anon-ws-disable-stacked-tor service for port 9150.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

sudo systemctl stop anon-ws-disable-stacked-tor_autogen_port_9150.socket sudo systemctl stop anon-ws-disable-stacked-tor_autogen_port_9150.service sudo systemctl stop anon-ws-disable-stacked-tor_autogen__run_anon-ws-disable-stacked-tor_127.0.0.1_9150.sock.socket sudo systemctl stop anon-ws-disable-stacked-tor_autogen__run_anon-ws-disable-stacked-tor_127.0.0.1_9150.sock.service

3. Prevent default anon-ws-disable-stacked-tor systemd unit from starting.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

sudo systemctl mask anon-ws-disable-stacked-tor_autogen_port_9150.socket sudo systemctl mask anon-ws-disable-stacked-tor_autogen_port_9150.service sudo systemctl mask anon-ws-disable-stacked-tor_autogen__run_anon-ws-disable-stacked-tor_127.0.0.1_9150.sock.socket sudo systemctl mask anon-ws-disable-stacked-tor_autogen__run_anon-ws-disable-stacked-tor_127.0.0.1_9150.sock.service

4. Install the local socks proxy server.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

A) Add Debian source repository.

Open file /etc/apt/sources.list.d/debian-src.list in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/apt/sources.list.d/debian-src.list

Qubes-Whonix

NOTES:

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

sudoedit /etc/apt/sources.list.d/debian-src.list

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/apt/sources.list.d/debian-src.list

Paste.

deb-src https://deb.debian.org/debian bookworm main contrib non-free

Save and exit.

sudo apt update

B) Install build dependencies.

sudo apt build-dep dante-server

C) Get dante source code.

apt-get source dante-server

D) Open the dante accesscheck.c source file.

mousepad ~/dante-1.4.2+dfsg/sockd/accesscheck.c

Paste the contents. Here we rewrite the authentication method to always return true. For the reasons see Dev/Dante.

/* * Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2005, 2006, 2008, * 2009, 2010, 2011, 2012, 2013 * Inferno Nettverk A/S, Norway. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. The above copyright notice, this list of conditions and the following * disclaimer must appear in all copies of the software, derivative works * or modified versions, and any portions thereof, aswell as in all * supporting documentation. * 2. All advertising materials mentioning features or use of this software * must display the following acknowledgement: * This product includes software developed by * Inferno Nettverk A/S, Norway. * 3. The name of the author may not be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * Inferno Nettverk A/S requests users of this software to return to * * Software Distribution Coordinator or sdc@inet.no * Inferno Nettverk A/S * Oslo Research Park * Gaustadalléen 21 * NO-0349 Oslo * Norway * * any improvements or extensions that they make and grant Inferno Nettverk A/S * the rights to redistribute these changes. * */ #include "common.h" static const char rcsid[] = "$Id: accesscheck.c,v 1.89 2013/10/27 15:24:42 karls Exp $"; int usermatch(auth, userlist) const authmethod_t *auth; const linkedname_t *userlist; { /* const char *function = "usermatch()"; */ const char *name; if ((name = authname(auth)) == NULL) return 0; /* no username, no match. */ do if (strcmp(name, userlist->name) == 0) break; while ((userlist = userlist->next) != NULL); if (userlist == NULL) return 0; /* no match. */ return 1; } int groupmatch(auth, grouplist) const authmethod_t *auth; const linkedname_t *grouplist; { const char *function = "groupmatch()"; const char *username; struct passwd *pw; struct group *groupent; SASSERTX(grouplist != NULL); if ((username = authname(auth)) == NULL) return 0; /* no username, no match. */ /* * First check the primary group of the user against grouplist. * If the groupname given there matches, we don't need to go through * all users in the list of group. */ if ((pw = getpwnam(username)) != NULL && (groupent = getgrgid(pw->pw_gid)) != NULL) { const linkedname_t *listent = grouplist; do if (strcmp(groupent->gr_name, listent->name) == 0) return 1; while ((listent = listent->next) != NULL); } else { if (pw == NULL) slog(LOG_DEBUG, "%s: unknown username \"%s\"", function, username); else if (groupent == NULL) slog(LOG_DEBUG, "%s: unknown primary groupid %ld", function, (long)pw->pw_gid); } /* * Go through grouplist, matching username against each groupmember of * all the groups in grouplist. */ do { char **groupname; if ((groupent = getgrnam(grouplist->name)) == NULL) { swarn("%s: unknown groupname \"%s\"", function, grouplist->name); continue; } groupname = groupent->gr_mem; while (*groupname != NULL) { if (strcmp(username, *groupname) == 0) return 1; /* match. */ ++groupname; } } while ((grouplist = grouplist->next) != NULL); return 0; } #if HAVE_LDAP int ldapgroupmatch(auth, rule) const authmethod_t *auth; const rule_t *rule; { const char *function = "ldapgroupmatch()"; const linkedname_t *grouplist; const char *username; char *userdomain, *groupdomain; int retval; if ((username = authname(auth)) == NULL) return 0; /* no username, no match. */ #if !HAVE_GSSAPI if (!rule->state.ldap.ldapurl) SERRX(rule->state.ldap.ldapurl != NULL); #endif /* !HAVE_GSSAPI */ if ((userdomain = strchr(username, '@')) != NULL) ++userdomain; if (userdomain == NULL && *rule->state.ldap.domain == NUL && rule->state.ldap.ldapurl == NULL) { slog(LOG_DEBUG, "%s: cannot check ldap group membership for user %s: " "user has no domain postfix and no ldap url is defined", function, username); return 0; } if ((retval = ldap_user_is_cached(username)) >= 0) return retval; /* go through grouplist, matching username against members of each group. */ grouplist = rule->ldapgroup; do { char groupname[MAXNAMELEN]; slog(LOG_DEBUG, "%s: checking if user %s is member of ldap group %s", function, username, grouplist->name); STRCPY_ASSERTLEN(groupname, grouplist->name); if ((groupdomain = strchr(groupname, '@')) != NULL) { *groupdomain = NUL; /* separates groupname from groupdomain. */ ++groupdomain; } if (groupdomain != NULL && userdomain != NULL) { if (strcmp(groupdomain, userdomain) != 0 && strcmp(groupdomain, "") != 0) { slog(LOG_DEBUG, "%s: userdomain \"%s\" does not match groupdomain " "\"%s\" and groupdomain is not default domain. " "Trying next entry", function, userdomain, groupdomain); continue; } } if (ldapgroupmatches(username, userdomain, groupname, groupdomain, rule)){ cache_ldap_user(username, 1); return 1; } } while ((grouplist = grouplist->next) != NULL); cache_ldap_user(username, 0); return 0; } #endif /* HAVE_LDAP */ int accesscheck(s, auth, src, dst, emsg, emsgsize) int s; authmethod_t *auth; const struct sockaddr_storage *src, *dst; char *emsg; size_t emsgsize; { int match, authresultisfixed; match = 1; /* * HACK-FORK-EDIT-OK */ return match; }

E) Change directory into the dante source code folder.

pushd dante-1.4.2+dfsg

F) Build the Debian package.

dpkg-buildpackage -b --no-sign

E) Change directory back to the home folder.

popd

F) Install the modified dante package.

sudo dpkg -i dante-server_1.4.2+dfsg-7_amd64.deb

G) Block updates of dante-server.

sudo apt-mark hold dante-server

5. Open file /etc/danted.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/danted.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/danted.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/danted.conf

6. Local socks proxy configuration.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

Delete all contents from the file and replace it with the following configuration.

debug: 0 logoutput: stderr internal: 127.0.0.1 port = 9150 external: eth0 socksmethod: none username clientmethod: none user.privileged: root user.notprivileged: root user.libwrap: root # allow connections only from localhost client pass { from: 127.0.0.1/8 port 1-65535 to: 0.0.0.0/0 log: connect disconnect error # comment on some logs if you don't want to keep them } socks pass { from: 0.0.0.0/0 to: 0.0.0.0/0 command: bind connect udpassociate log: error connect disconnect iooperation }

7. Restart the local socks proxy.

This is to apply the changed configuration and to test if the configuration is valid.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

sudo systemctl restart danted.service

8. tb-starter Configuration

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In whonix-workstation-17 Template.

Stop Tor from using unix domain socket files for socks so it uses socks on IP 127.0.0.1 port 9150 instead.

Open file /etc/torbrowser.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/torbrowser.d/50_user.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/torbrowser.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/torbrowser.d/50_user.conf

Paste.

unset TOR_SOCKS_IPC_PATH

Save and exit.

9. Platform specific notice:

  • Non-Qubes-Whonix: No special notice required.
  • Qubes-Whonix: Shutdown Template. Once done, restart App Qube.

10. Start Tor Browser.

  • Non-Qubes-Whonix: In Whonix-Workstation.
  • Qubes-Whonix: In Whonix-Workstation App Qube.

torbrowser

Tor Browser should now be using system default networking thanks to the local socks proxy.

No additional configuration of Tor Browser is required.

11. Done.

Older Methods:

For older methods, which might be broken due to Tor Browser changes by upstream, please press on Expand on the right.

To enable transparent torification (no proxy setting), set the TOR_TRANSPROXY=1 environment variable. There are several methods, but the simplest is the /etc/environment Method.

Note: Choose only one method to enable transparent torification.

/etc/environment Method

This will apply to the whole environment, including any possible custom locations of Tor Browser installation folders. [4]

1. Platform specific notice.

2. Open file /etc/environment in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/environment

Qubes-Whonix

NOTES:

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

sudoedit /etc/environment

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/environment

3. Add the following line.

TOR_TRANSPROXY=1 ## newline at the end

4. Save and exit.

5. Reboot.

Reboot is required to make changes to configuration file /etc/environment take effect.

6. Done.

/etc/environment method configuration has been completed.

Tor Browser Settings Changes

This step is required since Tor Browser 10. [5]

1. Platform specific notice.

2. Tor Browser → URL bar → Type: about:config → Press Enter key. → search for and modify

3. network.dns.disabled → set to false

4. extensions.torbutton.launch_warning → set to false

Undo

Reverting this change is undocumented. Simply unsetting that environment variable will not work due to Tor Browser limitations. The easiest way to undo this setting is to install a fresh instance of Tor Browser (please contribute to these instructions)!

Command Line Method

1. Platform specific notice:

2. Navigate to the Tor Browser folder.

cd ~/.tb/tor-browser

3. Every time Tor Browser is started, run the following command to set the TOR_TRANSPROXY=1 environment variable.

TOR_TRANSPROXY=1 ./start-tor-browser.desktop

4. Done.

start-tor-browser Method

This only applies to a single instance of the Tor Browser folder that is configured. This method may not persist when Tor Browser is updated.

1. Platform specific notice:

2. Find and open start-tor-browser in the Tor Browser folder with an editor.

This is most likely found in ~/.tb/tor-browser/Browser/start-tor-browser below #!/usr/bin/env bash.

3. Set.

export TOR_TRANSPROXY=1

4. Done.

start-tor-browser Method configuration has been completed.

Ignore Tor Button's Open Network Settings

Whonix has disabled the Open Network Settings... menu option in Tor Button. Read the footnote for further information. [6]


Deactivate Miscellaneous Proxy Settings

On the Stream Isolation page, there is a list of applications that are pre-configured to use socks proxy settings via application configuration files. To disable this the Whonix system default must be removed from the application's settings.

TODO: document and expand.

Remove proxy settings for APT repository files.

1. Platform specific notice:

2. If you previously onionized any repositories, that has to be undone; see Onionizing Repositories.

3. Remove any mention of tor+ in file /etc/apt/sources.list (if it was previously configured; that file is empty by default in Whonix / Kicksecure) or any file in folder /etc/apt/sources.list.d.

4. Open file /etc/apt/sources.list /etc/apt/sources.list.d/* in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/apt/sources.list /etc/apt/sources.list.d/*

Qubes-Whonix

NOTES:

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

sudoedit /etc/apt/sources.list /etc/apt/sources.list.d/*

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/apt/sources.list /etc/apt/sources.list.d/*

5. Remove any mention of tor+.

6. Done.

The process of removing proxy settings from APT repository files is now complete.

Remove proxy settings for Tor Browser Downloader by Whonix.

1. Platform specific notice:

2. Open file /etc/torbrowser.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/torbrowser.d/50_user.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/torbrowser.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/torbrowser.d/50_user.conf

3. Paste. [8] [9]

TB_NO_TOR_CON_CHECK=1 CURL_PROXY="--fail"

4. Save and exit.

5. Done.

Proxy settings have been removed from Tor Browser Downloader by Whonix (and Mullvad Browser by Kicksecure developers).

For some applications, this is impossible:

These applications can only talk to Tor Onion Services directly and cannot be configured to use the system default. Therefore you can only deactivate sdwdate and/or not use applications like OnionShare and Ricochet IM.

Use a Fail Closed Mechanism[edit]

A general problem with VPNs is that connections often fail to remain open. This means the VPN connection suddenly closes, leaving the user directly connected to the Internet (without first tunneling through the VPN). This is not a Whonix-specific problem. VPN servers and software can occasionally fail without prior notice. Therefore, if the VPN is unreachable or the connection breaks down for whatever reason, in most cases the user will continue to connect to the Internet without the VPN.

One of the key benefits of Whonix is that when a VPN connection fails, protection is still provided by the Tor process. In this instance, the Whonix-Workstation will seamlessly continue to make "direct" connections through Tor. Failure of the VPN tunnel may be inconsequential if a VPN is only used to circumvent Tor censorship. On the other hand, if VPN use is intended to improve security, then it must be configured so that if/when the VPN connection fails, all connections between the outside world and the computer are halted.

Instructions below include a fail closed mechanism.

VPN Client Choice[edit]

  • It is recommended to utilize OpenVPN.
  • Using Bitmask VPNarchive.org for this use case is not possible. [10] In other words, you cannot use userTorbitmaskInternet. [11]
  • Other VPN clients are unsupported.

Set Up Tor before a VPN (User → Tor → VPN → Internet)[edit]

Introduction[edit]

Two configurations are available:

Separate VPN-Gateway[edit]

Info Platform specific notice.

This configuration has a separate VPN-Gateway between Whonix-Gateway and Whonix-Workstation: Whonix-WorkstationVPN-GatewayWhonix-Gateway.

UserTorVPNInternet

There used to be a Qubes specific bug breaking this. [12] It has probably been fixed at least since Qubes R4.2. Please try and report if this worked for you so this notice can be removed.

1. Prerequisite knowledge: Qubes VPN Setup over Clearnet

"Forget" about Whonix for a moment for this step 1. This is about Qubes only. This is unspecific to Whonix.

The user needs to master setting up the VPN-Gateway as per Qubes VPN Documentationarchive.org in context of a "normal" VPN using clearnet. Meaning, without involving, mentioning Whonix in any way. Connection scheme: UserVPNInternet

It is recommended to follow the Set up a ProxyVM as a VPN gateway using iptables and CLI scriptsarchive.org instructions because this prevents clearnet leaks if/when the VPN breaks down.

Two options. Choose one.

Note:

  • UDP: UDP-style VPN connections are incompatible with Tor because it requires the VPN to be configured to use TCP. [13] This requires adding proto tcp to the VPN configuration file /rw/config/vpn/openvpn-client.ovpn. Nearly all VPN providers support this configuration.
  • Support: Please do not contact Whonix support for this step because mastering this skill is specific to Qubes only.

2. Clone a Template.

For example, clone debian-12 and name the new template clone debian-12-vpn. [14]

Qube Managerdebian-12Clone qubeEnter name for Qube clone: debian-12-vpnPress: OK

3. Create a new ProxyVM based on the newly cloned template.

Name the VM VPN-Gateway and set the Whonix-Gateway ProxyVM (sys-whonix) as NetVM. Make sure to check [✔] the box for "provides network".

Qube ManagerQubeCreate new qube

  • Name and label: VPN-Gateway (Set the preferred color)
  • Type: Qube based on a template (AppVM)
  • Template: debian-12-vpn
  • Networking: sys-whonix
  • Advanced: [] Provides network
  • Press: OK

4. Torified VPN Setup

Setup the VPN-Gateway. This will be similar to step 1. This will result in connection scheme UserTorVPNInternet because in above step Networking: sys-whonix has been configured.

Notes:

  • VPN Provider Choice: A VPN provider different from the VPN provider used in step 1 should be used. This is because the VPN provider from step 1 knows you real IP address. The VPN provider used for connection scheme UserTorVPNInternet should only know your Tor exit relay IP address.
  • Fail closed mechanism: Without configuring a fail closed configuration, all traffic originating from the Whonix-Workstation App Qube (anon-whonix) would only be forced through Tor if/when the VPN connection breaks down (UserTorInternet).
  • UDP vs TCP: Reminder. Only TCP can be used as mentioned in step 1.

5. Check the VPN-Gateway is fully functional.

Test connectivity from inside the VPN-Gateway as per Qubes VPN Documentationarchive.org.

6. Recommended: Prevent bypassing of the tunnel link.

In Whonix-Workstation (anon-whonix), apply instructions from the Prevent Bypassing of the Tunnel-Link section.

7. Optional: Leak tests.

It is recommended to run the related Leak Tests.

8. Done.

The VPN-Gateway configuration is complete.

Notes:

  • No DNS configuration is required when using a separate VPN Gateway and system DNS should work out of the box. [15]
  • For troubleshooting, see footnote. [16]
  • Whonix user forum discussion: Set up a VPN in ProxyVM over sys-whonixarchive.org [17]
  • The following warning will appear when using Tor Browser and is expected (see technical footnote): [18]
Something Went Wrong!
Tor is not working in this browser.

Inside Whonix-Workstation[edit]

This configuration will connect to the VPN using your preferred software inside the (Whonix-)Workstation.

Note that UDP-style VPN connections are incompatible with Tor; the VPN must be configured to use TCP. [19] This requires adding proto tcp to the VPN configuration file /etc/openvpn/openvpn.conf. Nearly all VPN providers support this configuration.

UserTorVPNInternet

Whonix TUNNEL_FIREWALL vs Standalone VPN-Firewall[edit]

When applying VPN instructions inside Whonix VMs, do not use the standalone VPN-Firewall. It is not required and is incompatible with the integrated Whonix TUNNEL_FIREWALL feature which is documented below.

Preparation[edit]

NOTE: might be broken, see https://forums.whonix.org/t/user-tor-vpn-internet-doesnt-work-in-whonix-16/13786archive.org

It is challenging to set up OpenVPN on Whonix with a secure, leak-preventing Fail Closed Mechanism. For this reason, it is strongly recommended to first exercise outside of Whonix and learn how to set up OpenVPN on Debian stable (currently bookworm). The following steps are a simple overview of the process:

  1. "Forget" about Whonix for a while
  2. Prepare a Debian bookworm VM.
  3. Install the Debian OpenVPN package: sudo apt install openvpn.
  4. Research how to set up a VPN using OpenVPN on the command line. Only proceed if this is successful. Please do not post support requests regarding these instructions before completing this basic exercise as this is unspecific to Whonix.
  5. Search for help with general VPN setup in the VPN Setup section or in the VPN Tunnel Setup Examples chapter. Help is available from various sources, and the VPN provider may also be of assistance.
  6. Only then proceed attempting to replicate a similar setup with Whonix.

Prerequisite Knowledge[edit]

Before proceeding, it is strongly recommended to read and understand the Whonix Debian Packages chapter.

Firewall Settings[edit]

Modify Whonix-Workstation User Firewall Settings

Note: If no changes have yet been made to Whonix Firewall Settings, then the Whonix User Firewall Settings File /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-Workstation 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-Workstation App Qube (commonly called anon-whonix)Whonix User Firewall Settings

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

Start MenuApplicationsSystemUser Firewall Settings

If using a terminal-only Whonix-Workstation, complete these steps.

Open file /usr/local/etc/whonix_firewall.d/50_user.conf with root rights.

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

The Whonix Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_workstation_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.

Also see: 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-workstation-17Whonix Global Firewall Settings

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

Start MenuApplicationsSettingsGlobal Firewall Settings

If using a terminal-only Whonix-Workstation, complete these steps.

In Whonix-Workstation, open the whonix_firewall configuration file in an editor. nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf

Add the following settings.

WORKSTATION_FIREWALL=1
TUNNEL_FIREWALL_ENABLE=true

Save.

Reload Firewall[edit]

Reload Whonix-Workstation Firewall.

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

Qubes App Launcher (blue/grey "Q")Whonix-Workstation App Qube (commonly named anon-whonix)Reload Whonix Firewall

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

Start MenuApplicationsSystemReload Whonix Firewall

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

sudoers Configuration[edit]

Open file /etc/sudoers.d/tunnel_unpriv in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/sudoers.d/tunnel_unpriv

Qubes-Whonix

NOTES:

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

sudoedit /etc/sudoers.d/tunnel_unpriv

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/sudoers.d/tunnel_unpriv

Edit the file so the text looks looks like the following code block.

Note: This might include removing comments (#) and adding text. Do not remove the lines with double hashes (##).

tunnel ALL=(ALL) NOPASSWD: /bin/ip
tunnel ALL=(ALL) NOPASSWD: /usr/sbin/openvpn *
Defaults:tunnel !requiretty
Defaults:tunnel env_keep += script_type
Defaults:tunnel env_keep += dev

Save and exit.

VPN Setup[edit]

Info Update: The Riseup "legacy" VPN appears to have been discontinued. The Riseup replacement service (Bitmask) has not been tested. If you do not have a Riseup invite code then tailor the instructions in this section to work with any other OpenVPN provider.

Introduction[edit]

info The following example uses the Riseup VPN, because it is known to support TCP, UDP and SSL. However, any preferred VPN provider can be used.

Get VPN Certificate[edit]

  1. Inspect the Riseup Certificate Authorityarchive.org page and download (right-click) the Riseup CA certificatearchive.org. [20]
  2. Advanced users can optionally verify the Riseup CA certificatearchive.org before storing it. [21]
  3. Store the certificate in /etc/openvpn/RiseupCA.pem:

curl --tlsv1.3 https://help.riseup.net/security/network-security/riseup-ca/RiseupCA.pem | sudo tee /etc/openvpn/RiseupCA.pem

VPN Credentials[edit]

For this example, for this step, a Riseup account is required. Unfortunately, the former free VPN service is no longer available. [22] This means to create an account you will need an "invite code" from a current Riseup user.

  • If you have one:
  • If you do not have an invite code:
    • Please do not ask Whonix developers or forums for an invite code because none will be available.
    • Instead tailor the instructions in this section to work with any other OpenVPN provider.

1. Open file /etc/openvpn/auth.txt in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/openvpn/auth.txt

Qubes-Whonix

NOTES:

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

sudoedit /etc/openvpn/auth.txt

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/openvpn/auth.txt

2. Add.

Note: Replace riseupusername with the actual Riseup user name and replace vpnsecret with the actual user name and password or just go to account.riseup.netarchive.org, log in and click on "VPN".

riseupusername
vpnsecret

3 . Save and exit.

VPN IP Address[edit]

When editing the VPN configuration file the use of DNS hostnames is not supported. This means IP address(s) of the VPN must be used. [23] Therefore, vpn.riseup.net cannot be used, but an IP address such as 198.252.153.226 should be used instead. To discover the IP address, check with the VPN provider or use nslookup on the host operating system (OS) (outside any virtual machine (VM)). For example, to verify the actual IP address of the vpn.riseup.net DNS server, run.

nslookup vpn.riseup.net

VPN Configuration File[edit]

1. Open file /etc/openvpn/openvpn.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/openvpn/openvpn.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/openvpn/openvpn.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/openvpn/openvpn.conf

2. Add.

Note: It is necessary to adjust the remote 198.252.153.226 80 variable in the configuration below unless you are using nyc.vpn.riseup.net as the VPN service. Replace the IP (198.252.153.226) and port (80) to match your VPN service.

##############################
## VPN provider specific settings ##
##############################
auth-user-pass auth.txt

## using nyc.vpn.riseup.net 80
remote 198.252.153.226 80

ca RiseupCA.pem

remote-cert-tls server

####################################
## TUNNEL_FIREWALL specific settings ##
####################################
client
dev tun0
persist-tun
persist-key

script-security 2
up "/etc/openvpn/update-resolv-conf script_type=up dev=tun0"
down "/etc/openvpn/update-resolv-conf script_type=down dev=tun0"

user tunnel
iproute /usr/bin/ip_unpriv

############################################
## Connecting to Tor before a VPN specific settings #
############################################

proto tcp

[24] [25]

3. Save.

Install resolvconf[edit]

Update the package lists.

sudo apt update

Install resolvconf. [26]

sudo apt install resolvconf

Users preferring not to install resolvconf should read the footnotes. [27]

DNS Configuration[edit]

1. Open file /usr/lib/tmpfiles.d/50_openvpn_unpriv.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /usr/lib/tmpfiles.d/50_openvpn_unpriv.conf

Qubes-Whonix

NOTES:

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

sudoedit /usr/lib/tmpfiles.d/50_openvpn_unpriv.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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 /usr/lib/tmpfiles.d/50_openvpn_unpriv.conf

2. Add. [28]

d       /run/resolvconf 0775    root      tunnel    -       -
d       /run/resolvconf/interface         0775      root    tunnel    -    -

Save the file.

3. Adjust permissions. [28]

sudo chown --recursive root:tunnel /run/resolvconf

sudo chmod --recursive 775 /run/resolvconf

4. Open file /etc/resolvconf/run/interface/original.resolvconf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/resolvconf/run/interface/original.resolvconf

Qubes-Whonix

NOTES:

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

sudoedit /etc/resolvconf/run/interface/original.resolvconf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/resolvconf/run/interface/original.resolvconf

Comment everything out by adding a # in front of all entries. Alternatively, empty or delete that file. [29]

Save and exit.

Additional Setup[edit]

Configuration Folder Permissions[edit]

Since OpenVPN will be run under user tunnel, that user requires read access to the folder /etc/openvpn.

sudo chown -R tunnel:tunnel /etc/openvpn

sudo chown -R tunnel:tunnel /run/openvpn

systemd Setup[edit]

1. Create the OpenVPN systemd service file.

sudo cp /lib/systemd/system/openvpn@.service /lib/systemd/system/openvpn@openvpn.service

2. Enable the OpenVPN systemd service file.

sudo systemctl enable openvpn@openvpn

3. Start the OpenVPN systemd service.

sudo systemctl start openvpn@openvpn

4.Check the OpenVPN systemd service status.

sudo systemctl status openvpn@openvpn

resolvconf Adjustments[edit]

Restart resolvconf. [30]

sudo service resolvconf restart

Verify DNS Settings[edit]

1. Open the /etc/resolv.conf file.

sudo cat /etc/resolv.conf

2. Check the current settings.

It should not include the following setting; this is the standard Whonix DNS server.

nameserver 10.152.152.10

It should also not include the following settings; these are the standard Qubes DNS servers.

nameserver 10.137.3.1
nameserver 10.137.3.254

3. Confirm it only includes the DNS server of your DNS provider.

For example.

nameserver 10.5.0.1

systemcheck[edit]

systemcheck configuration. systemcheck cannot work in this configuration out of the box. Perform the following steps to unbreak it.

1. Open file /etc/systemcheck.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /etc/systemcheck.d/50_user.conf

Qubes-Whonix

NOTES:

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

sudoedit /etc/systemcheck.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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/systemcheck.d/50_user.conf

2. Add the following text.

systemcheck_skip_functions+=" check_tor_bootstrap " systemcheck_skip_functions+=" check_tor_socks_port_reachability " systemcheck_skip_functions+=" check_tor_socks_port " systemcheck_skip_functions+=" check_tor_trans_port " systemcheck_skip_functions+=" check_stream_isolation " systemcheck_skip_functions+=" download_whonix_news " ## {{ Alternative to disabling check_tor_trans_port. ## Make the Tor TransPort test work by simulating the Tor SocksPort test succeeded. #CHECK_TOR_RESULT_SOCKS_PORT=0 ## Do not warn if Tor was not detected. (Will be the VPN.) #SYSTEMCHECK_NO_EXIT_ON_TRANS_PORT_DETECTION_FAILURE=1 ## }} ## {{ Alternative to download_whonix_news. ## Download news through system default. #CURL_PROXY_WHONIX_NEWS="--fail" ## }}

3. Save the file.

4. Done.

systemcheck configuration has been completed.

Qubes-specific[edit]

Info This is a placeholder; ignore this Qubes-specific section for now. TODO.

1. When using an App Qube, persistent changes require the Qubes bind dirs mechanism.

sudo mkdir /rw/config/qubes-bind-dirs.d

2. Open file /rw/config/qubes-bind-dirs.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix

This box uses sudoedit for better security.

sudoedit /rw/config/qubes-bind-dirs.d/50_user.conf

Qubes-Whonix

NOTES:

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

sudoedit /rw/config/qubes-bind-dirs.d/50_user.conf

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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 /rw/config/qubes-bind-dirs.d/50_user.conf

3. Add the following content.

binds+=( '/etc/sudoers.d/tunnel_unpriv' )
binds+=( '/etc/openvpn' )
binds+=( '/lib/systemd/system/openvpn@openvpn.service' )
binds+=( '/etc/systemd/system/multi-user.target.wants/openvpn@openvpn.service' )

TODO: This does not work yet because the files need to exist first.

/usr/lib/qubes/bind-dirs.sh umount
/usr/lib/qubes/bind-dirs.sh

Test[edit]

1. Test the ping functionality.

Utilize a suitable IP address such as Google's DNS server or an alternative server of your choice.

ping 8.8.8.8

2. Test DNS to check it correctly resolves a suitable domain.

Utilize check.torproject.org or an alternative server of your choice.

nslookup check.torproject.org

3. Test DNS and output IP address.

systemcheck_skip_functions="" \
CHECK_TOR_RESULT_SOCKS_PORT=0 \
WHONIXCHECK_NO_EXIT_ON_TRANS_PORT_DETECTION_FAILURE=1 \
whonixcheck --function check_tor_trans_port

Additional Information[edit]

The procedure is complete. If you have any issues, refer to the Troubleshooting section below. Once the setup is functional, it is recommended to perform Leak Tests.

Troubleshooting[edit]

You can skip this troubleshooting chapter unless any difficulties are encountered.

ip_unpriv vs ip-unpriv[edit]

There are two similar, yet distinct projects: standalone VPN-FIREWALL and Whonix TUNNEL_FIREWALL. Although both are alike, there is one difference that might be encountered. For instance, in the VPN Configuration File section:

  • Whonix TUNNEL_FIREWALL uses ip_unpriv (underscore)
  • Standalone VPN-FIREWALL uses ip-unpriv (hyphen)

Be sure to use the right version of ip unpriv depending on whether VPN-FIREWALL or Whonix TUNNEL_FIREWALL is in use.

50_openvpn_unpriv.conf vs 50_openvpn-unpriv.conf[edit]

Like the example above:

  • Whonix TUNNEL_FIREWALL uses /usr/lib/tmpfiles.d/50_openvpn_unpriv.conf ip_unpriv (underscore)
  • Standalone VPN-FIREWALL uses /usr/lib/tmpfiles.d/50_openvpn-unpriv.conf ip-unpriv (hyphen)

Cannot ioctl TUNSETIFF[edit]

 ERROR: Cannot ioctl TUNSETIFF tun: Operation not permitted (errno=1)

In openvpn.conf do not use.

dev tun

Use.

dev tun0

Dev tun Mismatch[edit]

In openvpn.conf do not use.

dev tun

Use.

dev tun0

/run/openvpn/openvpn.status Permission denied[edit]

 Options error: --status fails with '/run/openvpn/openvpn.status': Permission denied

To avoid permission issues, do not:

  • start OpenVPN as root; or
  • use sudo openvpn.

Files in the /run/openvpn folder are owned by root, so they cannot be overwritten by the user tunnel.

debug start[edit]

To start debug, run the following commands successively.

sudo /usr/sbin/openvpn --rmtun --dev tun0 sudo /usr/sbin/openvpn --mktun --dev tun0 --dev-type tun --user tunnel --group tunnel cd /etc/openvpn/ sudo -u tunnel openvpn /etc/openvpn/openvpn.conf

Linux ip link set failed[edit]

 Linux ip link set failed: external program exited with error status: 2

Use ip_unpriv as documented above.

Connectivity Test[edit]

1. Check if TCP is functional.

  • without DNS:
    • The following command uses an IP address 116.202.120.181.
    • UWT_DEV_PASSTHROUGH=1 curl --tlsv1.3 --proto =https -H 'Host: check.torproject.org' -k https://116.202.120.181/api/ip

2. Check if DNS + TCP is functional.

  • with DNS:
    • The following command uses a hostname check.torproject.org.
    • UWT_DEV_PASSTHROUGH=1 curl --tlsv1.3 --proto =https https://check.torproject.org/api/ip

DNS Configuration[edit]

This only applies if resolvconf is in use.

Permissions on two directories may need to be manually changed if they are not automatically applied. Check if changes are necessary with the following command.

ls -la /run/resolvconf

If the output lists tunnel as having read / write / execute permissions for both /run/resolvconf and /run/resolvconf/interface, then nothing needs modification. If tunnel is not listed as a group for one or both directories, then permissions need to be changed. In that case, run.

sudo chown --recursive root:tunnel /run/resolvconf

Then set the necessary permissions.

sudo chmod --recursive 775 /run/resolvconf

In /run/resolvconf, resolv.conf may or may not be owned by tunnel, depending on whether the systemd service has already started. There is no need to modify permissions on this file, as the permissions will change when the service starts.

Terminology for Support Requests[edit]

Phrases such as "over Tor" are ambiguous. Please do not coin idiosyncratic words or phrases, otherwise this leads to confusion. Please use the same terms that are consistently referenced in documentation, such as:

  • Connect to a VPN Before Tor (UserVPNTorInternet).
  • Connect to Tor Before a VPN (UserTorVPNInternet).
  • And so on.

Always refer to the connection scheme when requesting support, such as:

  • UserVPNTorInternet, or
  • UserTorVPNInternet.

How to Submit a Support Request[edit]

Before submitting a support request for VPN-related issues, users are encouraged to follow the Self Support First Policy to work towards a solution. Whonix developers will use the reported information to determine if the issue is a technical problem (legitimate bug) and/or configuration error which is a common cause of VPN connectivity issues.

Before Whonix developers will review the support request, the following information is required:

  • Steps to reproduce the behavior. For example, list all command that were run up to this point. [31]
  • A detailed explanation of actual behavior. Incomplete reports stating the "VPN does not work" will be rejected.
  • Expected behavior. Reports simply stating "VPN works" will be rejected.

The following technical information is also necessary:

  • All error messages.
  • VPN logs from the debug start section:
  • Confirmation of whether the VPN configuration has been modified aside from the instructions on this page.
    • Note: Users are encouraged to troubleshoot their VPN issues in an effort to find a solution. However, if the VPN was modified with custom configuration options, a favorable outcome is less likely if this information is not shared with Whonix developers.
  • Confirmation of whether Whonix is configured to use a second tunnel-link/proxy or bridge.
  • If applicable, whether links to similar issues were found on the Whonix forumsarchive.org and/or other offsite forums/resources.

Leak Tests[edit]

Introduction[edit]

It is important to verify the network traffic configuration enforces UserTorVPNInternet and not only UserTorInternet. Therefore, it is recommended to run the following related leak tests inside Whonix-Workstation. Test Tor Browser, a uwt wrapper deactivated application, as well as a regular application for leaks.

Regular Application Test[edit]

Use curl without pre-configured stream isolation.

UWT_DEV_PASSTHROUGH=1 curl --silent --tlsv1.3 https://check.torproject.org | grep IP

[32] [33]

The output should show something similar to: Your IP address appears to be: xxx.xxx.xxx.xxx
It should also list the VPN's IP address.

uwt-wrapped Application Test[edit]

Connect to check.torproject.org.

curl --silent --tlsv1.3 https://check.torproject.org | grep IP

[32] [34]

Browser IP Test[edit]

This test can be skipped if Tor Browser will not be used through the VPN.

If everything was configured correctly, test the setup. Open https://check.torproject.orgarchive.org in Tor Browser. It will state "You are not using Tor." and the VPN's IP address will be visible. In fact this means the VPN was tunneled through Tor first because Whonix-Workstation can not make any non-Tor connections by design (everything is tunneled over Tor).

DNS Leak Test[edit]

Other Leak Tests[edit]

Advanced users can also run a multiple additional, general leak tests that are unrelated to tunneling. However, these are more difficult to perform and are targeted at developers rather than general users. For further information, see: Leak Tests.

Footnotes[edit]

  1. Qubes-Whonix users note: Or alternatively in App Qube.

    1. Create folder /usr/local/etc/uwt.d.

    sudo mkdir -p /usr/local/etc/uwt.d

    2. Open with root rights: sudoedit /usr/local/etc/uwt.d/50_user.conf

  2. This term was coined in context of a Tor Transparent Proxyarchive.org (.oniononion). It acts as a simple gateway that routes all connections through Tor, but does not provide Stream Isolation.
  3. If these settings are changed, Tor Button would previously show a red sign and state "Tor Disabled" when a mouse was hovered over it.
  4. Unless this environment variable is manually unset before starting Tor Browser.
  5. The regular Tor Browser Bundle from The Tor Project (without Whonix) allows networking settings to changed inside Tor via the Open Network Settings menu option. It has the same effect as editing Tor's config file torrc. In Whonix, the environment variable export TOR_NO_DISPLAY_NETWORK_SETTINGS=1 has been setarchive.org to disable the Tor BrowserOpen Network Settings... menu item. It is not useful and confusing to have in the Whonix-Workstation because:
  6. Qubes-Whonix users note: In App Qube (whonix-workstation-17) could also use file /usr/local/etc/torbrowser.d/50_user.conf instead.

    1. Create folder /usr/local/etc/torbrowser.d (if using Tor Browser Downloader by Whonix developers) and optionally /usr/local/etc/mullvadbrowser.d (if using Mullvad Browser by Kicksecure developers).

    mkdir -p /usr/local/etc/torbrowser.d

    mkdir -p /usr/local/etc/mullvadbrowser.d

    2. Open file /usr/local/etc/torbrowser.d/50_user.conf in an editor with root rights.

    Non-Qubes-Whonix

    This box uses sudoedit for better security.

    sudoedit /usr/local/etc/torbrowser.d/50_user.conf

    Qubes-Whonix

    NOTES:

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

    sudoedit /usr/local/etc/torbrowser.d/50_user.conf

    • After applying this change, shutdown the Template.
    • All App Qubes based on the Template need to be restarted if they were already running.
    • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

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

    And/or:

    sudoedit /usr/local/etc/mullvadbrowser.d/50_user.conf

  7. TB_NO_TOR_CON_CHECK=1 needs to be set because there is no filtered Tor ControlPort access when Whonix tunnel firewall is enabled, which would break tb-updater's Tor connectivity check.
  8. By tb-updater default, if unset, variable CURL_PROXY will be dynamically set to a Tor SocksPort on Whonix-Gateway. For example to CURL_PROXY="--proxy socks5h://user:password@10.137.6.1:9115".
    By utilizing a curl parameter we are using anyhow -- CURL_PROXY="--fail" -- the environment variable can be disabled even if it is technically still set. This will result in downloading via the system's default networking.
  9. https://0xacab.org/leap/bitmask-vpnarchive.org
  10. Previously Bitmask did not support Tor. Broken link: https://github.com/leapcode/bitmask_client/issues/1009
  11. See UDP.
  12. At the time of writing Debian 11 bullseye was the stable release version.
  13. This is because a properly configured Qubes VPN-Gateway will be able to resolve DNS.
    • Check the VPN-Gateway is fully functional. Test connectivity from inside the VPN-Gateway.
    • When testing the VPN connection do not add any VMs that have been previously used for non-anonymous activities behind the VPN-Gateway. This will burn the VPN, making it unsuitable for use with Whonix!
    • Create a fresh, newly created VM if intending to use a non-Whonix VM behind the VPN-Gateway for testing purposes.
  14. This is because Tor Browser can no longer access Tor's ControlPort (onion-grater) on Whonix-Gateway.
  15. See UDP.
  16. Riseup notes:

    Every CA (certificate authority) has a file that is distributed publicly. This file, called a “CA certificate”, is used by your local program to confirm the identity of servers you connect with.

  17. If verification is not performed, then it is impossible to know the correct certificate was downloaded and that connections are secure.
  18. Previously a VPN secret (VPN password) and username could be registered.
  19. Many VPN service providers include DNS hostnames in their configuration files. The hostnames typically include the providers name followed by (.net, .com, .ch, .pw).
  20. It is necessary to run OpenVPN as user 'tunnel' because that is the only user besides user clearnet that is allowed to establish external connections when using Whonix Firewall setting VPN_FIREWALL=1.
  21. /etc/openvpn/update-resolv-conf uses resolvconf. resolvconf needs to be installed for the lines beginning with script-security, up, and down to function properly.
  22. 1. In the /etc/openvpn/openvpn.conf file, change the following text.

    script-security 2
    up "/etc/openvpn/update-resolv-conf script_type=up dev=tun0"
    down "/etc/openvpn/update-resolv-conf script_type=down dev=tun0"
    

    To the following. Remove or comment out the lines beginning with "up" and "down", and change the 2 to a 1.

    script-security 1
    

    2. Open file /etc/resolv.conf in an editor with root rights.

    Non-Qubes-Whonix

    This box uses sudoedit for better security.

    sudoedit /etc/resolv.conf

    Qubes-Whonix

    NOTES:

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

    sudoedit /etc/resolv.conf

    • After applying this change, shutdown the Template.
    • All App Qubes based on the Template need to be restarted if they were already running.
    • This is a general procedure required for Qubes and unspecific to Qubes-Whonix.

    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/resolv.conf

    3. Comment out the nameserver.

    #nameserver 10.152.152.10
    

    4. Add the VPN provider's DNS server.

    ## Riseup.net OpenVPN DNS server
    nameserver 172.27.100.1
    

    If Riseup is not in use, replace 172.27.100.1 with the virtual LAN IP address of the VPN provider's DNS server. If unsure, the VPN provider might provide it. To try to infer it, run sudo route after successfully connecting to the VPN. The first destination default gateway should also function as a DNS server.

    5. Save and exit.

    6. Optional: Prevent /etc/resolv.conf being overwritten by other packages like DHCP or resolvconf.

    Run.

    sudo chattr +i /etc/resolv.conf
    

    In order to revert this change, use -i.

    Ignore the /etc/resolv.conf instructions below.

  23. 28.0 28.1 This is removeable since Whonix 14 because it was merged in the usablity-misc package.
  24. This is done to prevent the old DNS server being used. For further discussion of this issue, see: https://github.com/adrelanos/vpn-firewall/issues/16archive.org
  25. This ensures changes in /etc/resolvconf/run/interface/original.resolvconf from the DNS Configuration section take effect.
  26. To list previous commands, run. history
  27. 32.0 32.1 In the absence of functional system DNS, an alternative is to just test TCP. The IP 116.202.120.181 might change. To discover the current one, run the following command inside a VM with functional system DNS. (Ideally inside a Whonix-Workstation.) nslookup check.torproject.org
  28. UWT_DEV_PASSTHROUGH=1 curl --silent --tlsv1.3 -H 'Host: check.torproject.org' -k https://116.202.120.181 | grep IP
  29. curl --silent --tlsv1.3 -H 'Host: check.torproject.org' -k https://116.202.120.181 | grep IP

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!