How to Connect to a Proxy Before Tor in Whonix

Connecting to a proxy before Tor helps to evade censorship in some countries. It also mitigates the risk of being dependent on Tor alone. This article provides practical instructions to complement the material on this subject in the Whonix wiki. We demonstrate the procedure for two alternatives:

1. Shadowsocks

1.1. Install Shadowsocks-Libev

We are going to install the C version of the Shadowsocks client. On the Gateway virtual machine, open a terminal, and issue the commands:

sudo apt update
sudo apt install shadowsocks-libev -y

The installation places a default configuration file in /etc/shadowsocks-libev/config.json. It also creates the following default systemd service files:

After the install has finished, the shadowsocks-libev.service is active and running with the default configuration file.

1.2. Obtain Server Details

You will need one or more Shadowsocks servers you can connect to. The server may be set up by yourself or by a trusted friend. You can also use a free public-interest server. This has the additional advantage that your traffic will be mixed in with many other people's.

Shadowsocks server copnfigurations are usually distributed as Shadowsocks (“SS”) URLs. These are base-64 encoded strings that begin with the characters ss://. Here is an example of what an SS URL looks like:

ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTpiYXJmb28hQDQ1LjQ1LjQ1LjQ1OjgzODgK

The base-64 part of this can be decoded by the base64 --decode command:

echo 'Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTpiYXJmb28hQDQ1LjQ1LjQ1LjQ1OjgzODgK' | base64 --decode

This command yields a result like this:

chacha20-ietf-poly1305:barfoo!@45.45.45.45:8388

You must pick the parameters out of the result. Continuing this example, this gives you these configuration parameters:

1.3. Configure Shadowsocks-Libev

Edit the default configuration file, /etc/shadowsocks-libev/config.json.

Insert contents as follows, replacing the default parameters with the actual values for your server. Continuing the example from above, this would yield:

{
  "server": "45.45.45.45",
  "server_port": 8388,
  "local_address": "127.0.0.1",
  "local_port":1080,
  "password": "barfoo!",
  "method": "chacha20-ietf-poly1305",
  "timeout": 300,
  "fast_open": false,
  "nameserver": "8.8.8.8",
  "mode": "tcp_and_udp"
}

The parameters you specify on the client must match up with what you chose on the server.

Save the file /etc/shadowsocks-libev/config.json.

1.4. Configure Systemd

Edit the systemd service file /lib/systemd/system/shadowsocks-libev.service. Make the file look like this:

[Unit]
Description=Shadowsocks-Libev Local Client
Documentation=man:ss-local(1)
After=network.target
[Service]
Type=simple
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
User=tunnel
Group=tunnel
ExecStart=/usr/bin/ss-local -c /etc/shadowsocks-libev/config.json
[Install]
WantedBy=multi-user.target

Save the file /lib/systemd/system/shadowsocks-libev.service. Reload systemd for your changes:

sudo systemctl daemon-reload

1.5. Start Shadowsocks-Libev

Restart Shadowsocks-Libev with your new configuration:

sudo systemctl restart shadowsocks-libev

Check that the Shadowsocks-Libev client is running and listening:

sudo systemctl status shadowsocks-libev
ss -tulpn | grep 1080

1.6. Reconfigure Anon Connection Wizard

Tor on Whonix is controlled by the configuration files stored in the Gateway machine’s directory /usr/local/etc/torrc.d. We can write new torrc files automatically by reinvoking the Anon Connection Wizard:

sudo anon-connection-wizard
  1. Select Configure.
  2. Select bridges or not, as you prefer.
  3. Check the box to say you want to use a proxy before connecting to the Tor network.
  4. Specify the SOCKS5 proxy on 127.0.0.1 port 1080.
  5. Wait for the Tor bootstraping to reach 100%.
  6. Click Finish.

When the Anon Connection Wizard runs, it writes the new torrc to /usr/local/etc/torrc.d/40_tor_control_panel.conf. Advanced users can add extra parameters in /usr/local/etc/torrc.d/50_user.conf if they manually restart Tor afterwards.

Minimize the Gateway virtual machine.

1.7. Check Workstation

Go to the Workstation virtual machine. Open the Whonix Tor Browser. Do an end-to-end test of your connectivity by visiting https://check.torproject.org.

2. V2Ray

2.1. Install V2Ray

Install V2Ray on your Gateway virtual machine like this:

wget https://raw.githubusercontent.com/v2fly/fhs-install-v2ray/master/install-release.sh
sudo bash install-release.sh

2.2. Obtain Server Details

You will need a V2Ray server you can connect to. The server may be set up by yourself or by a trusted friend. You can also use a free public-interest server. This has the additional advantage that your traffic will be mixed in with many other people’s.

V2Ray servers are usually distributed as vmess URLs. These are base-64 encoded strings. There are actually two formats for the base-64 encoded vmess URLs.

The old format simply base-64 encodes the entire configuration. It looks like this:

vmess://ewoidiI6ICIyIiwKInBzIjogIjIzM3YyLmNvbV80NS40NS40NS40NSIsCiJhZGQiOiAiNDUuNDUuNDUuNDUiLAoicG9ydCI6ICIzMDcxOCIsCiJpZCI6ICJjZTVjOTU3OC0wMzFiLTQ3ZjMtOTEzZC04YzVmYTdmNjgyNmMiLAoiYWlkIjogIjIzMyIsCiJuZXQiOiAidGNwIiwKInR5cGUiOiAibm9uZSIsCiJob3N0IjogIiIsCiJwYXRoIjogIiIsCiJ0bHMiOiAiIgp9Cg==

The base-64 part of this can be directly decoded by the base64 --decode command:

echo 'ewoidiI6ICIyIiwKInBzIjogIjIzM3YyLmNvbV80NS40NS40NS40NSIsCiJhZGQiOiAiNDUuNDUuNDUuNDUiLAoicG9ydCI6ICIzMDcxOCIsCiJpZCI6ICJjZTVjOTU3OC0wMzFiLTQ3ZjMtOTEzZC04YzVmYTdmNjgyNmMiLAoiYWlkIjogIjIzMyIsCiJuZXQiOiAidGNwIiwKInR5cGUiOiAibm9uZSIsCiJob3N0IjogIiIsCiJwYXRoIjogIiIsCiJ0bHMiOiAiIgp9Cg==' | base64 --decode

Decoding the vmess URL yields a result like this:

{
"v": "2",
"ps": "233v2.com_45.45.45.45",
"add": "45.45.45.45",
"port": "30718",
"id": "ce5c9578-031b-47f3-913d-8c5fa7f6826c",
"aid": "233",
"net": "tcp",
"type": "none",
"host": "",
"path": "",
"tls": ""
}
The new format vmess URL has cleartext parameters at the end. Here you can decode the base-64 part of it with base64 --decode. You must pick the rest of the parameters out of the URL.

In either case, you must translate the supplied parameters into the configuration file’s equivalent JavaScript Object Notation (JSON). See the next section for an example.

2.3. Configure V2Ray

Edit the V2Ray configuration file, which is /usr/local/etc/v2ray/config.json.

Here is a simple example of V2Ray configuration for straight vmess protocol. Of course, you must substitute in your actual server’s values for the parameters in the template.

{
  "inbounds": [
    {
      "port": 1080, 
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "45.45.45.45", 
            "port": 30718,
            "users": [
              {
                "id": "ce5c9578-031b-47f3-913d-8c5fa7f6826c"
              }
            ]
          }
        ]
      }
    }
  ]
}

Here is a more realistic configuration for V2Ray + WebSocket + TLS. Note that you must specify the IP address and not the hostname of the vnext server, or it will not work in this scenario. Again, you must also substitute in your own values for the sample values in the template.

{
  "inbounds": [
    {
      "port": 1080,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"]
      },
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "45.45.45.45",
            "port": 443,
            "users": [
              {
                "id": "4db99e96-3ee3-419c-b1fb-2e4acc85ad74",
                "alterId": 64
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "tlsSettings": {
          "serverName": "xxx.example.com",
          "allowInsecure": false
        },
        "wsSettings": {
          "path": "/8snasdr9",
          "headers" : {
            "host": "xxx.example.com"
          }
        }
      }
    }
  ]
}

Save the file /usr/local/etc/v2ray/config.json.

2.4. Configure Systemd

Edit the systemd service file /etc/systemd/system/v2ray.service. Make the file look like this:

[Unit]
Description=V2Ray Service
After=network.target nss-lookup.target
[Service]
User=nobody
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
User=tunnel
Group=tunnel
ExecStart=/usr/local/bin/v2ray -config /usr/local/etc/v2ray/config.json
[Install]
WantedBy=multi-user.target
Save the file /etc/systemd/system/v2ray.service. Reload systemd for your changes:
sudo systemctl daemon-reload

2.5. Start V2Ray

Start V2Ray with your configuration:

sudo systemctl enable v2ray
sudo systemctl start v2ray

Check that the V2Ray client is running and listening:

sudo systemctl status v2ray
ss -tulpn | grep 1080

2.6. Reconfigure Anon Connection Wizard

Tor on Whonix is controlled by the configuration files stored in the Gateway machine’s directory /usr/local/etc/torrc.d. We can write new torrc files automatically by reinvoking the Anon Connection Wizard:

sudo anon-connection-wizard
  1. Select Configure.
  2. Select bridges or not, as you prefer.
  3. Check the box to say you want to use a proxy before connecting to the Tor network.
  4. Specify the SOCKS5 proxy on 127.0.0.1 port 1080.
  5. Wait for the Tor bootstraping to reach 100%.
  6. Click Finish.

When the Anon Connection Wizard runs, it writes the new torrc to /usr/local/etc/torrc.d/40_tor_control_panel.conf. Advanced users can add extra parameters in /usr/local/etc/torrc.d/50_user.conf if they manually restart Tor afterwards.

Minimize the Gateway virtual machine.

2.7. Check Workstation

Go to the Workstation virtual machine. Open the Whonix Tor Browser. Do an end-to-end test of your connectivity by visiting https://check.torproject.org.

3. Troubleshooting

If you experience any difficulties operating Whonix, visit the Whonix forums.

For Shadowsocks and V2Ray, you can ask questions on social media, or file legitimate issues on the appropriate GitHub issues page: