Connecting to a VPN before Tor

Whonix ®

Download

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

About

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

Docs

Documentation FAQ Troubleshooting

Community

Forums Contribute

Support

Self Support First Policy Search Engines, Docs and AI Support (Limited) Reporting Bugs Contact (Restricted)

Tools Upload file Special pages Recent changes Print Version Page meta What links here Related changes Page information

Page Read Edit History Move Protection Unwatch Watch Delete Purge

User Preferences Watchlist Contributions Logout Create account Login

Donate

Instructions on how to connect to a VPN before Tor.

User → VPN → Tor → Internet

Introduction

Whonix does not "need" a VPN. However, users have the option to use Whonix with a VPN. See the Tunnels/Introduction to learn more if that is useful or harmful.

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

Connecting to a VPN before Tor (User → VPN → Tor → Internet)

Introduction

Platform specific.

• Qubes-Whonix users have the option to use:
  • A) a #Separate VPN-Gateway and/or
  • B) could also install the VPN software #Inside Whonix-Gateway.
• Non-Qubes-Whonix users could install the VPN software
  • A) #On the Host OS (host operating system, outside of any VMs) and/or
  • B) #Inside Whonix-Gateway.

What's the difference of installing a VPN on the host OS versus installing on Whonix-Gateway?

	VPN Installed on the Host OS (outside any virtual machines)	VPN Installed on Whonix-Gateway™	VPN Installed on both the Host and Whonix-Gateway
All Whonix Traffic Routing	User → Host's VPN → Tor → Internet	User → Gateway's VPN → Tor → Internet	User → Host's VPN → Gateway's VPN → Tor → Internet
All Host Traffic Routing	User → Host's VPN → Internet	User → Internet	User → Host's VPN → Internet
Whonix-Gateway Compromise	Host's VPN Affords Protection	Nil Protection	Host's VPN Affords Protection

To decide the best configuration in your circumstances, consider:

• Is it necessary to hide all traffic from the ISP? Then install the VPN on the host.
• Should the VPN provider be able to see all traffic? Then install the VPN on the host.
• Should the VPN provider be limited to seeing Tor traffic, but not clearnet traffic? Then install the VPN on Whonix-Gateway.

VPN Client Choice

• Use OpenVPN.
• Using bitmask with Qubes is unsupported.
• Other VPN clients are unsupported.

Separate VPN-Gateway

Qubes-Whonix only! Non-Qubes-Whonix is unsupported!

A separate VPN-Gateway between Whonix-Gateway and sys-firewall, i.e.:

Whonix-Workstation → Whonix-Gateway → sys-vpn → sys-firewall → sys-net

User → VPN → Tor → Internet

These "Separate VPN-Gateway" instructions are new. You might be one of the first users. You might run into minor issues. Please test and report how it went.

1. Clone a Template for example, debian-12 and name the new template clone debian-12-vpn.

Qube Manager → debian-12 → Clone qube → Enter name for Qube clone: debian-12-vpn → Press: OK

2. Create a new ProxyVM based on the newly cloned template. Name the VM sys-vpn and set sys-firewall as NetVM. Make sure to check [✔] the box for provides_network.

Qube Manager → Qube → Create new qube

• Name and label: sys-vpn (Set any color)
• Type: AppVM
• Template: debian-12-vpn
• Networking: sys-firewall
• Advanced: [✔] Provides network
• Press: OK

3. Setup the VPN-Gateway as per Qubes VPN documentation. The instructions to configure the VPN gateway using iptables and CLI scripts is preferred to prevent clearnet leaks when the VPN breaks down.

Without a fail closed configuration, if the VPN breaks down, all traffic (such as DNS queries) originating from Whonix-Gateway (commonly called sys-whonix) would only be forced through Tor. (User → Tor → Internet)

When a failed closed configuration is used and the VPN connection breaks down, no traffic would leave Whonix-Gateway. This is what you want if you are reading this documentation chapter.

4. Check, that your sys-vpn is fully functional. Test connectivity from inside the sys-vpn as per: Qubes VPN Documentation

Note: Both TCP and UDP VPN connections should work. System DNS should work out of the box so no DNS configuration is required for Whonix-Gateway.

Done!

For troubleshooting, see footnote.

On the Host

Host in this context means the host operating system (outside any virtual machines).

Non-Qubes-Whonix only! (Because in Qubes, the host is non-networked by default. Qubes-Whonix users have the option to use a #Separate VPN-Gateway but could also install the VPN software #Inside Whonix-Gateway.)

User → VPN → Tor → Internet

When using a Whonix-Gateway virtual machine, connect to a VPN using software on the host operating system (and not on the Whonix-Workstation nor Whonix-Gateway).

Using software inside the host operating system may be more convenient if your more familiar with the host operating system than Whonix. Additionally, your VPN provider might provide custom software with tools for connecting to their servers. However, there are issues that you must consider:

• A VPN on the host operating system will route all traffic originating from the host through the VPN, as well as Whonix traffic. It is up to your preferences, if you like this or not.
• Your VPN software may not be designed or configured to "fail closed". That is, if your VPN session suddenly disconnects, your Tor connection will be automatically sent through your ISP without going through your VPN service.

How to add the VPN in Host OS

Use the host operating system's built-in tools connect to your VPN or use the software provided by your VPN service.

Use a Fail Closed Mechanism

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.

If you want to enforce, that the VPN always gets used, try VPN-Firewall.

(Or if that works for you, install the VPN on the gateway instead, because it comes with an integrated TUNNEL_FIREWALL feature, i.e. stay away from the standalone VPN-Firewall when you set up a VPN on the gateway.)

KVM VPN Killswitch

Platform specific notice:

• KVM: For a simplified option is only available for Whonix KVM users, please press expand on the right side.
• Other platforms (such as VirtualBox or Qubes): Skip this chapter.

Optionally KVM users could also skip this chapter and use any of the other documentation on this wiki page.

There has been a lot of debate about a fail-closed mechanism or a kill switch for VPN users on Whonix. (Cutting off all traffic to Tor if the VPN drops).

VPN-Firewall covers all host VPN traffic. However, for users who wish to only ensure that traffic originating from Whonix-Gateway goes through a VPN inclusive of a fail-closed mechanism, but excluding host traffic from the VPN this seems like a very interesting solution.

This guide is for VPNs that are set up on the host. All that is needed is modification of Whonix-External.xml to reflect the following:

<network>
  <name>Whonix-External</name>
  <forward dev='tun0' mode='nat'/>
  <bridge name='virbr1' stp='on' delay='0'/>
  <ip address='10.0.2.2' netmask='255.255.255.0'>
  </ip>
</network>

This is the key component, specifically telling libvirt to use tun0 for NAT. <forward dev='tun0' mode='nat'/>

Libvirt will automatically create these iptables rules when the Whonix-External Network is started, only allowing established forwarded traffic between the Whonix Gateway and the tun0 interface.

-A FORWARD -m conntrack --ctstate ESTABLISHED -j ACCEPT
-A FORWARD -s 10.0.2.0/24 -i virbr1 -o tun0 -j ACCEPT

That’s it.

If your VPN connection drops, all Whonix connectivity will die instantly, because tun0 is the only target for NAT.

Thus, incoming traffic can’t reach because the the ESTABLISHED connection rule points to the internal IP of your tun0 interface (which is not assigned if the VPN drops) and outgoing doesn’t work either for the same reason.

Inside Whonix-Gateway

Whonix-Gateway can be configured to connect to a VPN server before Tor, as well as "fail closed", blocking all Tor traffic if the VPN disconnects.

User → VPN → Tor → Internet

VPN Client Choice

Use OpenVPN.

Using bitmask inside Whonix-Gateway for this use case is unsupported. And discouraged. Because bitmask modifies the firewall. Perhaps that can be configured or is safe. Reaching that and documenting bitmask is TODO, help welcome!

Other VPN clients are unsupported.

Whonix TUNNEL_FIREWALL vs standalone VPN-Firewall

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.

Setup Time

If you are interested in hide Tor and Whonix from the ISP (read that page first)... After installing Whonix-Gateway, do the following steps before activating Tor in Whonix Setup Wizard.

Preparation

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.

Firewall Settings

Modify Whonix-Gateway^™ User Firewall Settings.

Note: If no changes have yet been made to Whonix Firewall Settings, then the Whonix User Firewall Settings File /usr/local/etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix^™, complete these steps.
In Whonix-Gateway App Qube. Make sure folder /usr/local/etc/whonix_firewall.d exists.

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

Qubes App Launcher (blue/grey "Q") → Whonix-Gateway App Qube (commonly called sys-whonix) → Whonix User Firewall Settings

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

Start Menu → Applications → Settings → User Firewall Settings

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

In Whonix-Gateway, open the whonix_firewall configuration file in an editor.

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

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_gateway_default.conf.

Note: The Whonix Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_gateway_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When {{project_name_short}} is updated, this
## file may be overwritten.

See also Whonix modular flexible .d style configuration folders.

To view the file, follow these instructions.

If using Qubes-Whonix, complete these steps.

Qubes App Launcher (blue/grey "Q") → Template: whonix-gateway-17 → Whonix Global Firewall Settings

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

Start Menu → Applications → Settings → Global Firewall Settings

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

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

Add the following settings. You can skip comments (starting with #). Don't use ; for comments. Likely you do not need to either uncomment (removing the # in front) or modify VPN_INTERFACE / LOCAL_NET.

## Make sure Tor always connects through the VPN.
## Enable: 1
## Disable: 0
## DISABELD BY DEFAULT, because it requires a VPN provider.
VPN_FIREWALL=1

## For OpenVPN.
#VPN_INTERFACE=tun0

## Destinations you don not want routed through the VPN.
## 10.0.2.2-10.0.2.24: VirtualBox DHCP
#      LOCAL_NET="\
#         127.0.0.0-127.0.0.24 \
#         192.168.0.0-192.168.0.24 \
#         192.168.1.0-192.168.1.24 \
#         10.152.152.0-10.152.152.24 \
#         10.0.2.2-10.0.2.24 \
#      "

Save.

Reload Firewall

Reload Whonix-Gateway^™ Firewall.

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

Qubes App Launcher (blue/grey "Q") → Whonix-Gateway ProxyVM (commonly named sys-whonix) → Reload Whonix Firewall

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

Start Menu → Applications → System → Reload Whonix Firewall

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

sudoers Configuration

Inside Whonix-Gateway.

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

Non-Qubes-Whonix^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

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

Comment in the following and remove the single hashes (#) in front of all lines, but do not remove the double hashes (##). The edited file should look like this.

Use of wildcard / asterix * is non-ideal security wise.

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

Save and exit.

Introduction

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

TODO: Documentation bug fix required. Won't work without Tor being enabled. You need to get the certificate elsewhere and then File Transfer it into Whonix-Gateway.

1. Inspect the Riseup Certificate Authority page and download (right-click) the Riseup CA certificate.
2. Advanced users can optionally verify the Riseup CA certificate before storing it.
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

Inside Whonix-Gateway.

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

• If you have one:
  • 1. Navigate to the account creation page in Tor Browser.
  • 2. Enter the invite code.
  • 3. Choose a username unrelated to your real identity.
  • 4. Enter a strong password.
• 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^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

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.net, log in and click on "VPN".

riseupusername
vpnsecret

3 . Save and exit.

VPN IP Address

This cannot be done inside Whonix-Gateway since it by default does not system default DNS for its own traffic.

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

Inside Whonix-Gateway.

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

Non-Qubes-Whonix^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

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

Add.

Note: make sure to adjust the remote 198.252.153.226 80 variable in your config (unless you are using nyc.vpn.riseup.net as your 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

# Disabling any possible ipv6 auto-configuration since we have ipv6 disabled on our Whonix-Gateway
pull-filter ignore "dhcp-option DNS6"
pull-filter ignore "tun-ipv6"
pull-filter ignore "ifconfig-ipv6"

Do not worry about TCP mode on Whonix-Gateway. Using the VPN in TCP mode may be possible depending the services provides by your VPN provider, but is not required on Whonix-Gateway. The VPN in UDP mode should work just fine. Your pick.

Save.

DNS Configuration

DNS configuration, resolvconf, update-resolv-conf or similar is not required for Whonix-Gateway.

Configuration Folder Permissions

Inside Whonix-Gateway.

(Qubes-Whonix: In Template)

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

Inside Whonix-Gateway.

(Qubes-Whonix: In Template. )

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

Enable Tor

(Qubes-Whonix: If using a Template, shut down the Template and restart Whonix-Gateway (sys-whonix). )

Enable Tor using Anon Connection Wizard.

Troubleshooting

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

ip_unpriv vs ip-unpriv

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

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

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

In openvpn.conf do not use.

dev tun

Use.

dev tun0

Dev tun Mismatch

In openvpn.conf do not use.

dev tun

Use.

dev tun0

/run/openvpn/openvpn.status Permission denied

 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

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

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

Use ip_unpriv as documented above.

Connectivity Test

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

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

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 (User → VPN → Tor → Internet).
• Connect to Tor Before a VPN (User → Tor → VPN → Internet).
• And so on.

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

• User → VPN → Tor → Internet, or
• User → Tor → VPN → Internet.

How to Submit a Support Request

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.
• 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:
  • This can be found using the Troubleshooting section on this page.
  • Redact all sensitive information such as VPN server IP addresses; see Never Post Full System Logs or Configuration Files for a rationale.
  • VPN logs are required because a configuration error and/or mismatch may not produce a noticeable error.
• 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 forums and/or other offsite forums/resources.

Additional Tweaks / Recommendations / Troubleshooting

If having problems with the connection / Tor is not fully bootstrapped, please press on expand on the right.

You have may have to manually restart Tor. This is because the VPN may not be ready when Tor is attempting to connect, because the VPN connection initialization takes too long. Due to a bug in Tor, it won't keep trying to connect. To fix this, you may have to manually restart Tor after boot, if whonixcheck reports that Tor is not fully bootstrapped. The same may be necessary if your VPN software or connection temporarily broke down.

To Manually restart Tor:

Reload Tor.

After changing Tor configuration, Tor must be reloaded for changes to take effect.

Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.

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

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

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

Start Menu → Applications → Settings → Reload Tor

If you are using a terminal-only Whonix-Gateway, click HERE for instructions.

Complete the following steps.

Reload Tor.

sudo service tor@default reload

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

sudo -u debian-tor tor --verify-config

The output should be similar to the following.

Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf".
Configuration was valid

Leak Tests

When you shut down the VPN, neither Tor, nor Whonix-Gateway whonixcheck/apt/etc. nor Whonix-Workstation should be able to connect anywhere anymore.

Force Tor to wait for OpenVPN

Create a folder /etc/systemd/system/tor.service.d.

sudo mkdir /etc/systemd/system/tor.service.d

Create a file /etc/systemd/system/tor.service.d/50_user.conf.

Open file /etc/systemd/system/tor.service.d/50_user.conf in an editor with root rights.

Non-Qubes-Whonix^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

sudoedit /etc/systemd/system/tor.service.d/50_user.conf

Qubes-Whonix^™

NOTES:

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

sudoedit /etc/systemd/system/tor.service.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/systemd/system/tor.service.d/50_user.conf

Add the following content.

[Unit] After=openvpn.service

Save.

At next boot, the Tor daemon will be started after the OpenVPN daemon.

Debugging:

Limitations

• Only tested with OpenVPN. Most other VPNs have deficiencies anyway.
• DNS (IP address) of VPN server has to be manually resolved. There is technically no way to automatically resolve DNS without making the setup much more complex. The VPN server's IP address should not be resolved over Tor, because that's what you wanted to hide in the first place. Since outside observers will know, that you are connecting to the VPN IP anyway, it is probably safe to resolve the DNS over clearnet or by asking the VPN provider if they don't already document their IPs on their website anyway.
• No support for IPv6 yet.

Troubleshooting VPN → Tor

• If not connecting, see above to manually restart Tor
• Check your VPN software's logs.

• Test if you are able to connect using your VPN

1. Login as user clearnet.

sudo su clearnet

2. Try connecting to check.tpo. Note, at time of writing, it looked like usaip free trial is probably blocking SSL, therefore it might not work.

UWT_DEV_PASSTHROUGH=1 curl --silent --tlsv1.3 -H 'Host: check.torproject.org' -k https://116.202.120.181 | grep IP

Should show something along: Your IP address appears to be: xxx.xxx.xxx.xxx

3. Get back to normal user.

exit

Footnotes

Whonix The most watertight privacy operating system in the world.

Dark mode

Follow us on social media

Supported by Power Up Privacy

Whonix is proudly supported until 2025 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint 2012- 2024 ENCRYPTED SUPPORT LP

Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!