This article aims to walk you through solving common configuration mistakes and issues that can cause DNS lookups to fail for a VPN connection. However before continuing please make sure you have followed instructions in the Troubleshooting Connection Problems article to establish the cause of any issues using your VPN connection.

Checking For a DNS Problem

It's important to first establish you have a problem with your VPN connection's DNS setup before continuing. Often other configuration problems and routing problems can cause DNS lookups to fail, however ultimately it isn't the DNS configuration that is at fault.

Please refer to the "Unable To Use The VPN Connection" section in the Troubleshooting Connection Problems article and follow the steps to test your VPN connection. If you're sure you have a DNS problem after performing these steps, then please proceed to the troubleshooting sections below.

Checking the Connection Log

If you have established you have a DNS issue, you should first check the OpenVPN log for any relevant messages. Viscosity will automatically check for potential configuration problems with a VPN connection's DNS setup. If any problems are found, it will add a warning to the OpenVPN log with more information.

Common warnings and messages include:

WARNING: The DNS server <server> is not routed through the VPN connection. DNS lookups to this server may travel over a different network interface <interface>.: This warning indicates that the IP address of the DNS server isn't being routed through the VPN connection. This could result in DNS lookups failing, or unexpected DNS results. DNS lookups will not take place over the VPN connection. This warning typically indicates either incorrect DNS server/s have been specified, or a problem with the VPN connection's routing. In some rare instances this may be intentional and the warning can be ignored.

WARNING: Split DNS is being used however no DNS domains are present. The DNS server/s for this connection may not be used.: This indicates that the connection needs one or more DNS domains to be specified, or the DNS mode changed, for DNS to work correctly. Please refer to the article about this warning which covers how this warning can be resolved.

WARNING: A .local domain is present in the DNS domain list. The .local domain is reserved for mDNS. Using it as a DNS domain may cause DNS resolution attempts to fail or unexpected DNS behaviour.: The .local domain is a special domain reserved for use by mDNS. Using it as a standard DNS domain may cause DNS lookups to fail and break Split DNS setups. Please refer to the information in the Reserved Domains section for information about this warning.

WARNING: The DNS domain <domain> is already in use by interface <interface>. DNS resolution attempts for this domain may not use the VPN DNS server/s or fail to resolve.: This warning indicates that a VPN DNS domain is already in use on the computer. This could potentially cause DNS lookups to travel via a different network interface when using Split DNS. If this is a problem you should consider removing the DNS Domain from the listed network interface.

DNS change detected, restoring DNS settings: This message indicates that the DNS settings were changed by a process other than Viscosity, and Viscosity is restoring the DNS settings back to your VPN DNS settings. It's normal to see this message every now and then (for example when a DHCP renew occurs). However if you're seeing this message very often (for example every 60 seconds) it could indicate a clash with other software on your computer. Refer to the "Checking for Conflicting Software" section below for more information.

DNS change due to unreachable DNS server/s: This message indicates that one or more of your VPN DNS servers is no longer reachable over the network, and so your computer's operating system has removed it from the list of DNS servers. This typically indicates a VPN configuration problem, such as an invalid DNS server being specified or an invalid or missing network route. However in some instances it can also occur if your computer loses partial network connectivity due to a network change. If this error persists you should check your VPN connection's network routes, the local computer's network connection, and for any conflicting software.

Checking the DNS Mode

If DNS lookups aren't working over your connection as expected, and there are no obvious warnings in the connection log, it's possible your connection may be using the wrong DNS mode.

The most straightforward approach to see what DNS mode is being used for your connection is to view the OpenVPN log. Look for a message indicating the DNS mode, which should be one of "DNS mode set to Full", "DNS mode set to Split", or "DNS mode set to Off".

If the DNS mode is Off, it means no VPN DNS settings are being used. This could indicate no DNS servers have been set for the VPN connection, or the DNS mode has been set to Disabled. Please refer to the Configuring DNS and WINS settings article for information on how to set one or more DNS servers and/or change the DNS mode.

If the DNS mode is set to Split, it means that the VPN DNS servers will only be used for certain domains. Your computer's normal DNS server/s will be used for all other domains. If the DNS mode for your VPN connection is set to Split, and domains you expect to work aren't resolving, the DNS domains associated with your connection may not be correctly configured. Please see the "Checking Split DNS Settings" section below to check this. Alternatively, you may want to consider changing the DNS mode to Full mode if all DNS lookups should use your VPN DNS server/s.

If the DNS mode is set to Full, it means that the VPN DNS servers will be used for all lookups on your computer. This includes lookups for domains that may not be associated with the VPN connection. If DNS works correctly for domains available through the VPN connection, but not for other websites that should be accessible via your normal network connection, you may want to consider changing the DNS mode to Split mode.

For information about these modes, and how to change or configure the DNS mode being used, please refer to the Configuring DNS and WINS settings article.

Checking the DNS Servers

The DNS servers associated with a VPN connection will be listed in Viscosity's Details window, and also in the OpenVPN log.

To view the DNS server/s being used via the Details window, first open the Details window from Viscosity's main menu, and then click the "Display Traffic" icon (the second icon from the left) to display additional traffic and VPN connection information. The DNS server/s set for the VPN connection will be listed.

To view the DNS server/s being used via the OpenVPN log, look for a message like "DNS Server/s: 123.45.67.10, 123.45.67.11". If this message isn't listed, it means either the DNS mode is set to Off, or no DNS servers have been specified.

If the DNS server/s are not what you expect, or none are listed, the please refer to the Configuring DNS and WINS settings article for information on how to configure the VPN DNS settings.

Testing the DNS Servers

In many instances VPN DNS problems are actually caused by problems with the DNS servers themselves. It is a good idea to test the DNS servers while the VPN connection is connected to ensure that they respond correctly.

To test a DNS server, first identify a domain that you should be able to resolve through the VPN connection, for example "sparklabs.com", and the IP address of the DNS server you wish to test, for example "123.45.67.10". If you have multiple DNS servers, each one should be tested.

Mac

1. Open the Terminal application. This can be found at /Applications/Utilities/Terminal.app
2. Enter the following command into the window that appears, replacing "sparklabs.com" with the domain name you wish to look up and "123.45.67.10" with the address of your VPN DNS server. Press Return or Enter on your keyboard.
   
   nslookup sparklabs.com 123.45.67.10
   
   
3. If the domain was able to be resolved you should see one or more Address results listed. If instead you see an error message, such as "connection timed out" or "server can't find sparklabs.com" it may indicate a problem with your DNS server.
4. Quit Terminal from the File menu when finished

Important Note for Mac Users: The "nslookup" command should only be used when directly testing a DNS server as illustrated above. It should not be used for general DNS lookups or testing as it does not use macOS's DNS resolver system. For more information please see Looking Up Or Testing A Domain Name and Notes for Linux/Unix Users.

Windows

1. Open the Command Prompt or PowerShell application. This can be found by right clicking your Start button.
2. Enter the following command into the window that appears, replacing "sparklabs.com" with the domain name you wish to look up and "123.45.67.10" with the address of your VPN DNS server. Press Return or Enter on your keyboard.
   
   nslookup sparklabs.com 123.45.67.10
   
   
3. If the domain was able to be resolved you should see one or more Address results listed. If instead you see an error message, such as "DNS request timed out" or "server can't find sparklabs.com" it may indicate a problem with your DNS server.

If you encounter a problem resolving the domain, and you're sure it is correct and should be resolvable, then it likely indicates a problem with the DNS servers being used. It may indicate a routing issue with the VPN connection, a problem with the DNS servers themselves, or invalid DNS server addresses.

Checking Split DNS Settings

If your VPN connection's DNS mode is set to Split mode, it is important to check that the correct DNS domains have been specified. For example, if the domain you're trying to resolve is "test.mycompany.com", but "mycompany.com" hasn't been listed as a VPN DNS domain, then the VPN DNS servers will not be used for this lookup (and hence it'll likely fail) when using Split mode. If you are using Full DNS mode, this section can be skipped.

To view the DNS domain/s for your VPN connection, open the OpenVPN log for your VPN connection, and look for a message like "DNS Domains/s: example1.com, example2.com". This message should list all DNS domains associated with your connection. If this message isn't listed, it means either the DNS mode is set to Off, or no DNS domains have been specified.

If there are DNS domains missing, or none at all are specified, you can add or edit the DNS domains by following the instructions in the Configuring DNS and WINS settings article.

On macOS you can also check that the DNS domain settings have been correctly applied. Please see the Checking Which DNS Servers Are Being Used section in the Configuring DNS and WINS settings article for information on how to check your computer's Split DNS domain settings.

On Windows, Viscosity handles matching DNS servers to domains. However domains are still used for suffixing purposes and are appended to the DNS Suffix Search list. Please see the Checking Which DNS Servers Are Being Used section in the Configuring DNS and WINS settings article for information on how to check your computer's Split DNS domain suffix search list.

Checking for Conflicting Software

In some instances locally installed third-party software may attempt to modify your computer's DNS settings and override your VPN DNS server/s. Such software often includes DNS proxies, internet filtering and parental control applications, other VPN clients, and some network security software.

If your DNS settings are being changed shortly after connecting your VPN connection, or you're seeing a lot of "DNS change detected, restoring DNS settings" messages in the OpenVPN log, you should check to see whether any such software is installed. If found, try temporarily disabling and/or uninstalling the software and see if the issue persists.

One widely used piece of software is Cisco Umbrella which conflicts with Viscosity Windows. If Cisco Umbrella is installed, Viscosity Windows will attempt to disable the software when connecting, then re-enable the software when disconnecting. If you wish to use Cisco Umbrella instead of Viscosity's DNS system, you should set the DNS Mode to Off.

Checking Web Browser DNS Settings

If DNS requests appear to work correctly when testing from the Terminal or Command Prompt, but not from a web browser, you may need to check your web browser's DNS settings. Many modern web browsers can be manually configured to ignore the computer's DNS settings and instead use internal DNS-over-HTTPS (DoH) DNS servers. While this behaviour isn't enabled by default, if it has been turned on it may cause issues resolving internal VPN DNS domains.

Please see the Web Browsers With Custom DNS Settings section in the Configuring DNS and WINS settings article for more information.

Testing the DNS Setup

Once you're sure DNS is configured correctly for your VPN connection, you can test the DNS setup by attempting to look up a domain name. For instructions on how to do this please refer to Looking Up Or Testing A Domain Name.

DNS Works With Other VPN Clients

By default Viscosity will use Split DNS mode when connecting to a VPN connection that has a split-traffic setup. A split-traffic setup is a VPN connection that only sends certain traffic through it, while by default all other traffic will still use your normal network connection. This is a common setup for most workplace and enterprise VPN connections.

However most other VPN clients do not have Viscosity's powerful Split DNS support, and instead always use the VPN connection's DNS servers for all DNS lookups on your computer, even when using a split-traffic setup. If the required DNS domains have not been specified, it will appear that DNS requests with these other clients "work" when they don't work in Viscosity. However, these other clients are in-fact leaking all DNS lookups through the VPN connection, which can have important security and privacy implications.

This is easily resolved by either adding the appropriate DNS domains to the VPN connection (the recommended approach), or by changing the DNS mode to Full DNS. For more information please refer to the "Resolving the Warning" and "About Other VPN Clients" sections in the Warning: Split DNS is being used however no DNS domains are present article (even if this specific warning isn't listed in the log).