Troubleshooting Guide
Here are some common issues / problems that are frequently encountered.
Last updated
Here are some common issues / problems that are frequently encountered.
Last updated
Before contacting support, please see if the answer cannot be found here:
The client communicates with core to initiate the handshake through the secure proxy (which is also the enrollment service - more details about the architecture here), so it's critical it works and is properly configured.
Common problems may be:
proxy / enrollment isn't working
DEFGUARD_ENROLLMENT_URL is set incorrectly in core - if set incorrectly the client will try to connect to default URL which is "http://localhost:8080" and MFA will not work.
See the "Desktop client real-time/auto sync doesn't work" answer.
After enabling Multi-Factor Authentication for a location the configuration of the gateway changes. Without MFA peers (devices) are persistent (always in the Kernel memory) and gateway only changed the gateway configuration if a peer is added/removed/changed.
But when MFA is enabled peers are only added to the gateway after successful MFA on the client (and pre-shared key exchange with client and gateway to establish a dedicated key for the session).
Also there is a setting in the location named Peer Disconnect Threshold (seconds):
This setting specifies that if the peer is inactive for (defined seconds), the gateway should remove it from the configuration (as it should not be persistent since MFA is required).
So if you are disconnected from the location:
Check what is your setting for peer disconnect.
We have a known bug - that after disconnecting Defguard Desktop Client doesn't properly detect that and has a still active connection (and actually is disconnected). You need to reconnect. Also it's being fixed and will be released in 1.1 version of the client.
This error commonly occurs on Ubuntu 22. Defguard client internally calls resolvconf to set DNS servers. The only tested backend is systemd-resolved, so make sure you use it before proceeding further (systemctl status systemd-resolved).
On newer Ubuntu distributions (23 and up) resolvconf is, by default, a symbolic link to resolvectl and this is the recommended way of interacting with the system's DNS configuration. On Ubuntu 22 the symbolic link doesn't exist and the most straightforward way to fix this issue is to manually create it:
If this fails, one may also try installing one of the packages providing the resolvconf command, like openresolv or resolvconf but this has not been tested and may possibly cause issues with systemd-resolved, so proceed at your own risk.
The libwebkit2gtk-4.0-37 library which our client depends on is not available in the default apt package repositories on ubuntu 24.04. There is only libwebkit2gtk-4.1. Client installation is still possible, but requires using some workarounds, as described here: tauri-apps/tauri#9662.
The minimal installation workaround is to manually download and install the following packages (avoiding temporarily adding apt-sources):
If you are having problems with TOTP codes form 2FA/MFA (when logging in to defguard or when connecting to VPN) please make sure your clock on the server that defguard core is running is set properly.
Best would be to setup on the server NTP time synchronization.
If you have configured your defguard instance correctly, after connecting to the VPN you should be able to ping your VPN server, for example if you have the following setup:
after connecting to VPN you should be able to ping: 10.1.1.1.
Check if the VPN location configuration has changed. If it did and you do not have Enterprise license where real-time config sync is automatic, the user needs to update their client configuration by updating that instance manually.
If you are not able to ping the VPN server the most common problem is that you have chosen a network that may be in conflict with your other networks (local network, network from your Internet provider, etc.).
To examine your routing use on Mac and Linux netstat -rn command. Let's look at the example from above, the VPN network is: 10.1.1.0/24, let's look at the network route tabile:
In the example above you can see that the whole 10.0.0.0 network (with mask 255.0.0.0 eg /8) is routed through default device en0.
Because of the main routing 10.0.0.0/8 the VPN server routing the network 10.1.1.0/24 (which is included in 10.0.0.0/8) will not work.
Another common problem is that your server on which the gateway is working, has some firewall rules that interfere with VPN network. Please examine carefully ufw and iptables (even if ufw is disabled there may be iptables rules).
If a user has no access to the VPN location, sometimes admins forget that they change the VPN settings and change a group that is allowed to access the VPN location. If the user is not a part of that group which VPN location is configured to access:
will not be able to connect.
Defguard only manages VPN server configuration (for now, we are planning ACLs / firewall management) which means it basically configures the VPN integrace and peers.
Then when the client / user connects it actually establishes a secure tunel between their computer network and your server (that VPN interface).
From there, what happens to this traffic is the administrator role. The most common scenarious to do are:
add routing rules, so that the traffic from that interface/VPN IP network gets routed to your network - this approach gives the advantage that users VPN ip persists in the network and the user is visible with it's VPN ip in your local network
Masquerade or NAT - a common use case is to masquerade or NAT the traffic - which is actually required if you want users to access Internet from the VPN - this process is described in detailed in this tutorial.
