App Support.

We're here to help.

Migrating from OpenVPN 2.3 to OpenVPN 2.4

Viscosity 1.9 drops support for OpenVPN 2.3, and now only supports OpenVPN 2.4 connections. For the vast majority of users no migration changes are needed and connections will automatically work.

Viscosity has defaulted to using OpenVPN 2.4 for many years, and in cases where OpenVPN 2.3 was used OpenVPN 2.4 is backwards compatible and should continue to work. You will still be able to connect to OpenVPN servers running 2.3 or older versions.

OpenVPN 2.3 is end-of-life and so it is no longer being updated or maintained by the OpenVPN team. Furthermore, it only supports outdated versions of OpenSSL (which are also end-of-life), and hence it should be considered insecure moving forwards.

I've Updated to Viscosity 1.9 and Now I Can't Connect

If you were successfully connecting your VPN connections using an older version of Viscosity, but you can't after updating to Viscosity 1.9, then this likely means your copy of Viscosity was previously configured to use OpenVPN 2.3. Please follow the troubleshooting steps below to resolve the problem.

Step 1: Contact your VPN Provider

We highly recommend contacting your VPN Provider first. They should be able to supply you with an up to date configuration for OpenVPN 2.4 which you can import and connect without needing to do any troubleshooting.

If you are a server administrator, we also recommend updating your server and configuration for OpenVPN 2.4 where possible.

Step 2: Check for Removed Commands

OpenVPN 2.4 removes support for the "tls-remote" command. Connections will this option present will not be able to connect. They instead will instantly fail.

To check whether this applies for your connection, see whether a line starts with "tls-remote" in the advanced commands area for your VPN connection. Please see the Advanced Configuration Commands article for how to check and edit your connection's advanced commands.

If the "tls-remote" command is not listed, then this isn't the cause of your connection failing to connect. Please move onto Step 3 below.

If the "tls-remote" command is present, then as a temporary work-around you can simply remove the entire line that starts with "tls-remote", and then Save your changes. However please note that removing this command removes certain server validation checking, which could potentially make your connection susceptible to MITM attacks.

The "tls-remote" command has been replaced with the verify-x509-name command. If you are a server administrator, you should update to this new command. If you are a user, please follow the instructions in Step 1 above to contact your VPN Provider for an updated configuration.

Step 3: Compression Settings

If you are still unable to connect your VPN connection, or you are able to connect but not access any resources through the VPN connection, then there is likely a mismatch between the compression settings on the OpenVPN server and in Viscosity.

OpenVPN 2.4 introduces a new compression option, and it must be set to the correct value that matches the OpenVPN server. If you are unsure of what compression settings the server uses, please try each of the following steps until you have a working connection:

  • From the Viscosity menu, open the Preferences window. Select your connection, and then click the Edit button. Click on the Advanced tab and look at the advanced commands area. If you see a line starting with comp-lzo, write this whole line down, remove it, save your configuration and connect. If the connection is now working, there is nothing more to do.
  • If you are still having connection problems, if the line was comp-lzo no, edit your connection again, go to the Options tab, and set Compression to Off. Save and try again.
  • If the line was comp-lzo, comp-lzo yes or comp-lzo adaptive, go to the Options tab and set Compression to LZO. Save and connect to try again.
  • Finally, if you are still having problems, leave the Compression option to what you set it to during the above steps, add the comp-lzo command back that you deleted, save and try to connect again.

Further information about resolving mismatched compression settings can be found in the Warning: Bad compression stub decompression header byte article.

Further Troubleshooting

If you are still having connection issues after the above steps, the issue may not be related to updating to OpenVPN 2.4. Please try the steps listed in the Troubleshooting Connection Problems article.