Connecting to a VPN before Tor
- 1 Connecting to a VPN before Tor (User → VPN → Tor → Internet)
- 1.1 Introduction
- 1.2 VPN Client Choice
- 1.3 Separate VPN-Gateway
- 1.4 On the Host
- 1.5 Inside Whonix-Gateway ™
- 1.5.1 VPN Client Choice
- 1.5.2 Whonix ™ TUNNEL_FIREWALL vs standalone VPN-Firewall
- 1.5.3 Setup Time
- 1.5.4 Preparation
- 1.5.5 Firewall Settings
- 1.5.6 Reload Firewall
- 1.5.7 sudoers configuration
- 1.5.8 VPN Setup
- 1.5.9 systemd setup
- 1.5.10 Enable Tor
- 1.5.11 Troubleshooting
- 188.8.131.52 ip_unpriv vs ip-unpriv
- 184.108.40.206 50_openvpn_unpriv.conf vs 50_openvpn-unpriv.conf
- 220.127.116.11 Cannot ioctl TUNSETIFF
- 18.104.22.168 Dev tun Mismatch
- 22.214.171.124 /run/openvpn/openvpn.status Permission denied
- 126.96.36.199 debug start
- 188.8.131.52 Linux ip link set failed
- 184.108.40.206 DNS Configuration
- 220.127.116.11 Terminology for Support Requests
- 1.5.12 How to Submit a Support Request
- 2 Footnotes
Connecting to a VPN before Tor (User → VPN → Tor → Internet)
- Qubes-Whonix ™ users have the option to use a #Separate VPN-Gateway but could also install the VPN software #Inside Whonix-Gateway ™.
- Non-Qubes-Whonix ™ users could install the VPN software #On the Host or #Inside Whonix-Gateway ™.
What's the difference of installing a VPN on the host versus installing on Whonix-Gateway ™?
|VPN Installed on the Host||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 not yet documented.
- Other VPN clients are unsupported. We are not aware of any sane VPN client choices besides OpenVPN.
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
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 ™.
For troubleshooting, see footnote. 
On the Host
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.
(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.)
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
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 [archive]!
Other VPN clients are unsupported. We are not aware of any sane VPN client choices besides OpenVPN.
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.
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 .
It is challenging to set up OpenVPN on Whonix with a secure, leak preventing Fail Closed Mechanism. For this reason, it is strongly recommended that users to learn how to set up OpenVPN on Debian stable (currently buster). The following steps are a simple overview of the process:
- Prepare a Debian stable VM.
- Install the Debian OpenVPN package: sudo apt-get install openvpn
- Research how to set up a VPN using OpenVPN on the command line. 
- Search for help with general VPN setup in the #VPN Setup chapter or on the TestVPN page. Help is available from various sources, and the VPN provider may also be of assistance.
Modify Whonix-Gateway ™ User Firewall Settings
Add the following settings. You can skip comments (starting with  Likely you do not need to either uncomment (removing the in front) or modify / .). Don't use for comments.
## 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 \ # "
Reload Whonix-Gateway ™ Firewall.
/etc/sudoers.d/tunnel_unpriv in an editor with root rights.
(Qubes-Whonix ™: In TemplateVM)
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.
tunnel ALL=(ALL) NOPASSWD: /bin/ip tunnel ALL=(ALL) NOPASSWD: /usr/sbin/openvpn * Defaults:tunnel !requiretty
Save and exit.
The following example uses the free Riseup VPN, because it is known to support TCP, UDP and SSL. However, any preferred VPN can be used.
Update: The Riseup "legacy" VPN may have been discontinued, as it no longer works for the author of these instructions. The Riseup replacement service (Bitmask) has not been tested.
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 ™.
curl --tlsv1.2 --proto =https https://help.riseup.net/security/network-security/riseup-ca/RiseupCA.pem | sudo tee /etc/openvpn/RiseupCA.pem
For this step, a riseup.net account and Riseup account name is required. Go to https://user.riseup.net/users/riseupusername/vpn [archive] to obtain a VPN secret (VPN password). Below, replace "riseupusername" with the actual riseup user name, or just go to https://user.riseup.net [archive], login and click on "VPN".
/etc/openvpn/auth.txt in an editor with root rights.
(Qubes-Whonix ™: In TemplateVM)
Add the actual user name and password.
Save and exit.
VPN IP Address
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 18.104.22.168 should be used instead. To discover the IP address, check with the provider or use nslookup on the host. For example, to verify the actual IP address of the vpn.riseup.net DNS server, run.
VPN Configuration File
/etc/openvpn/openvpn.conf in an editor with root rights.
(Qubes-Whonix ™: In TemplateVM)
Note: make sure to adjust thevariable in your config (unless you are using as your VPN service). Replace the IP ( ) and port ( ) to match your VPN service.
############################## ## VPN provider specific settings ## ############################## auth-user-pass auth.txt ## using nyc.vpn.riseup.net 80 remote 22.214.171.124 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
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.
DNS configuration, resolvconf, update-resolv-conf or similar is not required for Whonix-Gateway ™. 
Configuration Folder Permissions
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 /var/run/openvpn
Create the OpenVPN systemd service file.
sudo cp /lib/systemd/system/openvpn@.service /firstname.lastname@example.org
Enable the OpenVPN systemd service file.
sudo systemctl enable openvpn@openvpn
Start the OpenVPN systemd service.
sudo systemctl start openvpn@openvpn
Check the OpenVPN systemd service status.
sudo systemctl status openvpn@openvpn
Enable Tor using Whonix ™ Setup Wizard.
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 chapter #VPN Configuration File:
- Whonix TUNNEL_FIREWALL uses ip_unpriv (underscore)
- Standalone VPN-FIREWALL uses ip-unpriv (hyphen)
Be sure to use the right version of ip unpriv according to whether the VPN-FIREWALL or Whonix TUNNEL_FIREWALL project is being used.
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 Mismatch
In openvpn.conf do not use.
/run/openvpn/openvpn.status Permission denied
Options error: --status fails with '/run/openvpn/openvpn.status': Permission denied
Do not start OpenVPN as root. Do not use sudo openvpn, because this will lead to permission issues. Files in the /run/openvpn folder are owned by root, so they cannot be overwritten by the user tunnel.
To start debug, run the following commands concurrently.
sudo /usr/sbin/openvpn --rmtun --dev tun0
sudo /usr/sbin/openvpn --mktun --dev tun0 --dev-type tun --user tunnel --group tunnel
sudo -u tunnel openvpn /etc/openvpn/openvpn.conf
Linux ip link set failed: external program exited with error status: 2
Use ip_unpriv as documented above.
This only applies if resolvconf is used.
Permissions on two directories may need to be manually changed if they are not automatically applied. Check if changes are necessary via 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 of these 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:
- How to Connect to a VPN Before Tor (User → VPN → Tor → Internet).
- How to Connect to Tor Before a VPN (User → Tor → VPN → Internet).
- And so on.
Always refer to the connection scheme when requesting support: User → VPN → Tor → Internet or User → Tor → VPN → Internet and so on.
How to Submit a Support Request
Before submitting a support request for VPN related issues users are encouraged to follow the Free Support Principle when working towards a solution. Whonix developers will use the information provided by the user to determine if the issue is a technical problem (aka bug) and/or configuration error which is a common reason for VPN connectivity issue.
Before Whonix developers will review the support request, the following information must be provided.
- Steps to reproduce the behavior. For example, list all command that were run up to this point.
- Actual behavior. (Detailed explanation. Reports stating "VPN does not work" will be rejected.)
- Expected behavior. (Reports stating "VPN works" will be rejected.)
The following information is also required.
- All error messages.
- VPN logs from debug start section. This can be found under Troubleshooting on this page. Make sure to redact all sensitive information such as VPN server IP addresses. For more on this see why you should Never Post Full System Logs or Configuration Files. VPN logs are required because a configuration error and/or miss-match may not produce an noticeable error.
- Please answer: Has the VPN configuration been modified aside from the instructions on this page?
Note: Users are encouraged to troubleshoot their VPN issues in an effort to find a solutions. However, if the VPN has been modified with custom configuration options, a favorable outcome is less likely if Whonix developers are not made aware of the modification.
- Please answer: Is Whonix currently configured to use a second tunnel-link/proxy or bridge?
- (If applicable) Links to similar issues found on the Whonix forums [archive] 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:
When you shut down the VPN, neither Tor, nor Whonix-Gateway ™ whonixcheck/apt-get/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.
/etc/systemd/system/tor.service.d/50_user.conf in an editor with root rights.
(Qubes-Whonix ™: In TemplateVM)
Add the following content.
At next boot, the Tor daemon will be started after the OpenVPN daemon.
- Only tested with OpenVPN. Most other VPN's 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.
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.
Should show something along: Your IP address appears to be: xxx.xxx.xxx.xxx
3. Get back to normal user.
- All traffic generated by the host and all applications running on the host. For example, Firefox, NTP, and anything else. This also includes traffic generated by Whonix ™.
- https://github.com/leapcode/bitmask_client/issues/1009 [archive]
- At the time of writing Debian 9 buster was the stable release version.
- Because Whonix-Gateway ™ does not require any clearnet DNS anyhow.
- Check, that your VPN-Gateway is fully functional. Test connectivity from inside the VPN-Gateway.
- Add a non-Whonix ™ VM behind your VPN-Gateway. For example, add a debian based AppVM behind your VPN-Gateway. Figure out if the VPN-Gateway works at all before involving Whonix ™.
- Only proceed if this is successful. Do not post support requests regarding these instructions before completing this basic exercise.
- That config file is a bash fragment.
- Many VPN service providers include DNS hostnames in their configuration files. The hostnames typically include the providers name followed by (.net, .com, .ch, .pw).
- The Tor software cannot transport UDP yet, but it does not have to in this case. (Reference: Tor#UDP.) Since the VPN connects over clearnet, UDP should just work as usual. Once the VPN is functional, Tor will have no issue to connect using it (without "knowing" it is over a VPN).
- The /usr/bin/ip_unpriv [archive] wrapper script is being provided by the usabilty-misc [archive] package. The /etc/sudoers.d/tunnel_unpriv [archive] wrapper script is being provided by the usabilty-misc [archive] package. The /email@example.com/50_unpriv.conf [archive] wrapper script is being provided by the usabilty-misc [archive] package.
- We must run OpenVPN as user 'tunnel', because that is the only user besides user clearnet that will be allowed to establish external connections when using Whonix ™ Firewall setting VPN_FIREWALL=1.
- Because Whonix-Gateway ™ by default has no and needs no system DNS for its own traffic. See Whonix-Gateway System DNS if you would like to read an explanation why that is so.
To list previous commands, run.
sudo systemctl daemon-reload
sudo systemctl status tor
sudo systemctl status tor@default
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.
Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)