App Support.

We're here to help.

Setting up an Obfuscation server with Obfsproxy and Viscosity

Obfuscation can be used to prevent your VPN connection being detected and/or blocked. Some administrators (such as wireless hot spots in cafes) choose to block VPN traffic on their network. By obfuscating your VPN connection, you can securely connect to your remote network resources or browse the internet privately while connected to such restricted networks.

Network administrators can use tools like Deep Packet Inspection (DPI) to classify and restrict traffic by protocol, such as HTTP, SSL, VPN, etc. Viscosity uses Obfsproxy to obfuscate its VPN traffic. Obfsproxy transforms the VPN traffic coming from your computer to make it look like whatever you choose, so that it is more difficult to restrict via DPI methods. There are a number of different methods Obfsproxy can use to disguise your traffic, including obfs2 which adds an encryption wrapper around your VPN traffic to stop it looking like any protocol in particular.

Ubuntu Setup


For this guide, we assume:

  • You have already installed the latest version of Ubuntu (16.04 at time of writing)
  • You have root access to this installation of Ubuntu
  • You have already setup a TCP (not UDP) OpenVPN server
  • You already have a copy of Viscosity installed on your client device

The OpenVPN server can be on this installation of Ubuntu, or another machine, it doesn't matter. If you haven't already setup an OpenVPN server, please check out our setup guides. Make sure to set the OpenVPN server protocol to TCP, not UDP. We also assume that this installation of Ubuntu is a fresh install, possibly with an OpenVPN server installed as well.

If you don't have a copy of Viscosity already installed on your client machine, then please check out this setup guide for installing Viscosity (Mac | Windows).

Getting Started

The steps outlined in this guide are performed via the command line interface (i.e. terminal) on your Ubuntu server. If you are running this server remotely, you will need to use the SSH application to connect securely between your client device and the server (to "SSH into" your server).

To begin, log in to the command line as root. Once logged in, we need to ensure that Ubuntu's repository list is up to date by typing the following:

apt-get update

This will run through and make sure Ubuntu knows about the most recent versions of packages that can be downloaded with apt-get. For obfs2, obfs3 and scramblesuit we will use obfsproxy. To install obfsproxy, type the following into the terminal:

apt-get install obfsproxy

For obfs4 we will use obfs4proxy. To install obfs4proxy, type the following into the terminal:

apt-get install obfs4proxy

You will be asked:

Do you want to continue? [Y/n] 

Type y.

Obfsproxy Server Configuration

Viscosity supports a range of obfuscation techniques, including: obfs2, obfs3, scramblesuit and obfs4. We will set up Obfsproxy to run as a background service, so that it will be automatically started at boot time. As such, if you are installing Obfsproxy on the same machine running your OpenVPN server, they will both be started simultaneously.

First, create a new service by typing:

nano /etc/systemd/system/obfsproxy.service

Now paste the following into the nano window:

Description=Obfsproxy Server

ExecStart=/usr/bin/obfsproxy --log-min-severity=info obfs2 --dest= server


The destination address is the address of your OpenVPN server. If your OpenVPN server is running on a different machine to your Obfsproxy machine, the destination address will be the IP address of the OpenVPN server machine. In this example, we have an OpenVPN server running on the same machine as our Obfsproxy server, so the address for the OpenVPN server is just localhost (

The destination port (1194 in our example) can be changed to whichever port you choose, however it must match the port your OpenVPN server is listening on.

The server address of indicates that the Obfsproxy server is listening for connections on all addresses. The server port (12345 in our example) can be also changed to the port of your choice, in the range: >1024 but <65535. This will be the port you connect to with Viscosity. You can also use port 443 if you are in a location where non-HTTP ports might be blocked.

This configuration is now complete for obfs2. For other obfuscation modes, we will need to make some changes.


To change to obfs3, simply replace obfs2 with obfs3 in the ExecStart line in our service configuration:

ExecStart=/usr/bin/obfsproxy --log-min-severity=info obfs2 --dest= server


Scramblesuit requires a bit more configuration. First off, scramblesuit requires a directory to store persistent extra information. Scramblesuit gets installed with an apparmor configuration to secure it. In this configuration is a predefined directory for where to store this information. First, we will need to create this directory with the following command in terminal:

mkdir -p /var/lib/tor/pt_state/scramblesuit

Next, we need to generate a password to use. To do this, type the following into terminal:

python -c 'import os,base64; print base64.b32encode(os.urandom(20))'

This will output a line of numbers and letters, make a copy of this, this is your password for scramblesuit which we will need below and for the client connecting.

Finally, we need to change the ExecStart line in the service. Replace YOURPASSWORD with the password you generated in the above step:

ExecStart=/usr/bin/obfsproxy --log-min-severity=info --data-dir=/var/lib/tor/pt_state scramblesuit --password=YOURPASSWORD --dest= server


obfs4 requires a completely different configuration as we are using a different program for it. As with scramblesuit, we also need somewhere to store some persistent information, so create a directory for obfs4 by typing the following into terminal:

mkdir -p /var/lib/tor/pt_state/obfs4

Next, we will need to create a configuration for obfs4proxy. Type the following into terminal:

nano /var/lib/tor/pt_state/obfs4/obfs4.config

Now paste the following into the nano window:


As above, TOR_PT_ORPORT value is the destination address, or the address of your OpenVPN server and can be changed accordingly.

TOR_PT_SERVER_BINDADDR is the address obfs4proxy listens for connections. indicates that obfs4proxy is listening on all interfaces, and 12345 indicates that obfs4proxy is listening on port 12345. You can change these as desired, but the obfs4- prefix must remain for this value. Please see the start of this section for more information.

Next, we will setup our service. As we are using a different program, it's a good idea to create a different service name. Type the following into terminal:

nano /etc/systemd/system/obfs4proxy.service

Now paste the following into the nano window:

Description=Obfsproxy Server

ExecStart=/usr/bin/obfs4proxy -enableLogging true -logLevelStr INFO


There is one final setup for obfs4. A password is generated for us unlike scramblesuit where we generate one before hand. To get this password, we need to do the following *after* starting the service for the first time. Type the following into terminal after starting the obfs4proxy service:

cat /var/lib/tor/pt_state/obfs4/obfs4_bridgeline.txt

You should see a line output that looks something like:


The string that appears in place of LONGSEQUENCEOFCHARACTERS is your password. Take a copy of this to use as the Key when configurating your connection in Viscosity.

Starting the Obfsproxy Server

Now that you have the service configured, you can start the Obfsproxy server. Replace 'obfsproxy' with 'obfs4proxy' below if you have configured obfs4, all other obfuscation methods use obfsproxy. Type into the terminal:

systemctl start obfsproxy.service

To check the Obfsproxy server status, enter:

systemctl status obfsproxy.service

To which it should reply with:

 obfsproxy.service - Obfsproxy
   Loaded: loaded (/etc/systemd/system/obfsproxy.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2017-06-20 18:43:26 PDT; 1s ago
 Main PID: 2502 (obfsproxy)
   CGroup: /system.slice/obfsproxy.service
           └─2502 /usr/bin/python /usr/bin/obfsproxy --log-min-severity=info obfs2 --dest= server

Jun 20 18:43:26 ubuntu systemd[1]: Started Obfsproxy.
Jun 20 18:43:27 ubuntu obfsproxy[2502]: 2017-06-20 18:43:27,203 [WARNING] Obfsproxy (version: 0.2.13) starting up.
Jun 20 18:43:27 ubuntu obfsproxy[2502]: 2017-06-20 18:43:27,204 [INFO] StaticDestinationServerFactory starting on 12345
Jun 20 18:43:27 ubuntu obfsproxy[2502]: 2017-06-20 18:43:27,204 [INFO] Starting factory 

Finally, to ensure that your Obfsproxy server is started at boot time, type:

systemctl enable obfsproxy.service

You can now configure your connection in Viscosity to redirect to this Obfsproxy server.

Setting Up Viscosity

The interface provided by the Mac and Windows versions of Viscosity are intentionally very similar. As such, we will focus our guide on the Mac version, pointing out any differences with the Windows version as they arise.

If you do not have Viscosity already running, start Viscosity now. In the Mac version you will see the Viscosity icon appear in the menu bar. In the Windows version you will see the Viscosity icon appear in the system tray.

Click the Viscosity icon in the menu bar (Windows: system tray) and select 'Preferences...':



This shows you the list of available VPN connections. We assume you have already created a connection to your OpenVPN server. If you haven't set created a Viscosity connection to your OpenVPN server, please check out our OpenVPN server guides. Select your previously configured connection and click "Edit":

Configuring the Connection

You will now need to modify the connection parameters as outlined below:

  1. In the General tab, replace the server address with the IP address of your Obfsproxy server. This will be unchanged if your Obfsproxy server is running on the same machine as your OpenVPN server.
  2. Update the port to the Obfsproxy port set in the configuration above (12345 in our example).
  3. The protocol must be set to TCP.

  4. Click the Transport tab.
  5. Set the obfuscation method to the obfuscation method selected in the Obfsproxy server configuration.
  6. You cannot use a proxy when using obfuscation, so make sure the "Connect using proxy" option is unchecked.
  7. (Optional) If a shared secret has been set, enter that into the Key field.

  8. Click the Save button.

Connecting and Using Your VPN Connection

You are now ready to connect. Click on the Viscosity icon in the menu bar (Windows: system tray) and select 'Connect DemoConnection'. That's it, you should see a notification that you're now connected!

To check that the VPN is up and running, you can use the Viscosity details window. Click the Viscosity menu bar (Windows: system tray) icon and select 'Details...'. This will bring up the details window.

This window will show you the traffic passing through the VPN connection.