Troubleshooting

Most issues appear as alerts on the overview page and the Gateways page in the partner panel. Start by checking the server itself. On Linux:

sudo nuvpn-gateway status

On Windows Server, run nuvpn-gateway status in a command prompt with administrator privileges. The output includes status and counters, but no employee names.

The gateway is offline

• The gateway reports to nuVPN every 60 seconds. If no report is received for 3 minutes, its status in the partner panel changes to Offline.
• After 15 minutes without a report, an email is sent to the partner’s contact address and the customer’s address, once per incident. The check runs every 10 minutes, so the email may arrive up to 10 minutes later.
• Check that the server is running, the nuVPN Gateway service is running, and the server has an internet connection.
• If only the connection to nuVPN is lost and the server itself is working, employees can keep working (see No connection to nuVPN servers). If the server or its network is down, employees cannot connect until service is restored.

UDP port

• Devices connect to the gateway over UDP. The default port is 51820. The address and port are shown when installation is complete.
• You need to open the port for inbound traffic to the server in the cloud provider’s firewall, on the office router (port forwarding), and on the server itself. On Linux, if ufw is enabled, the installer shows the command to use.
• The installer automatically detects the server’s public address, even when the server is behind a router. On Linux, you can specify a different address with the --endpoint parameter. The gateway never replaces an address set this way.
• nuVPN checks the UDP port from outside the network: it sends a WireGuard connection request to the gateway and waits for a response. The check runs after every change to the gateway’s address and at least once every 6 hours. In the panel’s gateway table, green UDP means the request reached the gateway, red means it did not, and gray means no current result is available yet.
• When UDP is red, the office router is usually not forwarding the port to the server. Set up port forwarding, then click Check now in the gateway table. You can check each gateway once per minute. For gateways running a version earlier than 1.0.8, the check is unavailable and shown in gray.
• The check does not give nuVPN access to the customer’s network: it can only complete a handshake with the gateway, and the gateway drops every packet the check sends.

Private address

• The Private address alert appears when the gateway’s profiles point to an internal address on the office network, such as 192.168.x.x or 10.x.x.x. Devices outside the office cannot connect to this type of address.
• This happens when the server is behind a router and no public address was specified during installation.
• If the gateway detected the address automatically, it replaces it with the public address seen by nuVPN when it next reports.
• The gateway never changes an address set by the IT administrator. If the address is incorrect, correct it in the gateway’s console settings.
• Profiles generated with the private address are not updated. Generate them again after correcting the address.
• Even when the address is correct, you need to forward the UDP port on the office router to the server (see UDP port).

NAT conflict on Windows

• On Windows, a server can have only one NAT network. Installation therefore stops if the server already has another NAT, a Hyper-V NAT network, Routing and Remote Access (RRAS), or Internet Connection Sharing.
• The installer shows the reason on a line beginning with BLOCKED and records it in the Event Log.
• To resolve this, install the gateway on a dedicated server or virtual machine, or remove the existing NAT if it is no longer needed.
• The VPN address range (the default is 10.77.0.0/22) must not overlap with the local network either. On Windows, the installer stops and suggests an alternative range. On Linux, it selects an available range automatically.

Active Directory sync

• The gateway reads the access group from the directory every 5 minutes.
• When the directory is unavailable, no one’s access is revoked. Employees whose accounts have been disabled in the directory can still connect until sync resumes. The IT administrator can manually revoke a device’s access in the console, and the revocation takes effect immediately.
• The User directory sync failed alert appears in the partner panel. If the failure lasts more than an hour, an email is sent to the partner.
• If the group is returned empty after previously having members, no one’s access is revoked, and an alert appears in the console.
• Check the connection from the gateway to the domain controller, the service account and its permissions (on Linux), and the access group name. The console includes a connection test.

Domain controller without a certificate

The gateway connects to the directory only over an encrypted connection. LDAPS and StartTLS require a certificate on the domain controller.

• On Windows Server, select the Signed and sealed connection mode in the console. The connection is encrypted using Kerberos or NTLM on port 389, without a certificate. The password is never sent in plain text.
• On Linux, you can connect only through LDAPS or StartTLS. If the domain controller has no certificate, the console shows a message with two options: install a certificate on the domain controller or install the gateway on Windows Server.

Protection against mass access revocation

• If a single sync would revoke access for more than 20% of devices enrolled through the directory, and more than 5 devices in total, the gateway does not revoke access for any of them.
• The revocations wait for operator approval in the console. The Bulk access revocation awaiting approval alert appears in the partner panel.
• The console has no button to reject the revocations. If the directory change was a mistake, correct it in the directory. If the number of revocations falls below the threshold at the next sync, the gateway revokes only the access that still needs to be revoked.
• You cannot see whose access is pending revocation in the partner panel. The customer’s IT administrator provides approval.

Device enrollment through Group Policy fails

The Group Policy logon script requests a profile for the user and computer from the gateway, and the gateway authenticates the user through Kerberos. Common causes of failure:

• The computer is not connected to the office network. Group Policy works only when the computer can reach the office network. An employee who works only from home receives the profile from the console.
• Authentication error (401). On a gateway installed on Windows Server, the SPN for the gateway name is missing: setspn -S HTTP/<fqdn> <DOMAIN>\<GATEWAY>$. The name must match the console certificate. On a gateway installed on Linux, automatic enrollment requires a keytab file and a service principal named HTTP/<fqdn>.
• The user is not authorized (403). The account is disabled or is not a member of the access group.
• The license is inactive (402). The trial has ended or the license has been revoked. Check the license status in the partner panel.
• Too many requests (429). The license has reached its rate limit: 200 profiles per hour and 2,000 per day. For an initial deployment in a large organization, enroll devices in stages.
• No connection to nuVPN servers (503). See No connection to nuVPN servers.

Where to find the error: when the gateway is installed on Windows Server, the script writes to %LOCALAPPDATA%\nuVPN\enroll.log on the employee’s computer. When the gateway is installed on Linux, the script writes to the computer’s Event Log (Application, source nuVPN, event 1001). The gateway console keeps an activity log.

For full setup instructions, see the Distribution through Group Policy guide.

No connection to nuVPN servers

• Devices that are already connected continue working with no time limit.
• You can still revoke access in the console because revocations are enforced on the gateway itself.
• You cannot generate new profiles until the connection is restored. An error appears in the console.
• The gateway retries the connection. After repeated failures, the interval between attempts increases to a maximum of 10 minutes. Even after the connection is restored, it may therefore take up to 10 minutes for the next report.
• The gateway’s status in the partner panel is Offline, even when the server itself is working.

Console lockout

• After 3 failed login attempts from the same IP address within 24 hours, the address is blocked for 24 hours. A successful login resets the count.
• To unblock an address on the server: on Linux, run sudo nuvpn-gateway unban <ip>, or sudo nuvpn-gateway unban --all to unblock all addresses. On Windows Server, run the same commands without sudo in a command prompt with administrator privileges.
• If you lose the password, the nuvpn-gateway reset-password command generates and displays a new one-time password. You must change it when you first sign in. On Linux, run the command with sudo. On Windows, run it in a command prompt with administrator privileges; it also replaces the initial-password.txt file. After running the command on Windows, restart the service to close open connections.
• Console access from the internet is blocked by design. Access it from the internal network or through the VPN.