VPN Connection Troubleshooting

VPN Connection Troubleshooting

Most Common Issue

99% of ARROW connectivity problems are caused by network firewalls blocking VPN traffic. If your device shows “offline” or you can’t connect, the client’s network is almost certainly blocking required ports.

This guide explains exactly how ARROW devices establish VPN connections, what ports are required, and how to diagnose and resolve connectivity issues.

How NetBird VPN Works

ARROW uses NetBird, an open-source VPN built on WireGuard, for secure device connectivity. NetBird uses several techniques to establish connections:

Connection Flow

ARROW Device → Internet → NetBird Cloud Services → Your VPN Client
                              ↓
                    1. Management API (control plane)
                    2. Signal Service (coordination)
                    3. STUN (NAT traversal)
                    4. TURN/Relay (fallback)

1. Management Connection: Device authenticates with NetBird’s management API
2. Signal Exchange: Devices exchange connection information via the signal service
3. Direct P2P Attempt: Using STUN, devices try to establish a direct WireGuard tunnel
4. Relay Fallback: If direct connection fails, traffic routes through relay servers

Tip

NetBird only needs outbound connections. No inbound ports need to be opened on the client’s firewall - all connections are initiated from inside the network.

Required Outbound Ports

The following ports must be allowed outbound from the network where the ARROW device is deployed:

Self-Hosted VPN Infrastructure

ARROW uses self-hosted NetBird infrastructure. Each organization has a dedicated VPN endpoint at [org].arrowvpn.io (e.g., acme.arrowvpn.io). Your organization’s specific address is provided during onboarding.

Critical Services

Service	Destination	Protocol	Port(s)	Purpose
Management API	[org].arrowvpn.io	TCP	443	Authentication & control plane
Signal Service	[org].arrowvpn.io	TCP	443	Peer coordination

P2P & NAT Traversal (STUN)

Service	Destination	Protocol	Port(s)	Purpose
STUN	[org].arrowvpn.io	UDP	80, 443, 3478, 5555	NAT traversal for direct connections

Relay Services (TURN)

Service	Destination	Protocol	Port(s)	Purpose
TURN	[org].arrowvpn.io	UDP	80, 443	Relay fallback
TURN	[org].arrowvpn.io	TCP	443-65535	Relay fallback (TCP)
Relay	*.arrowvpn.io	TCP	443	Relay servers

Wildcard Recommended

For simplicity, you can whitelist *.arrowvpn.io to cover all ARROW VPN endpoints. Alternatively, whitelist your specific organization domain [org].arrowvpn.io.

Complete Port Summary

For IT teams, here’s the complete list to whitelist (replace [org] with your organization’s subdomain):

# Essential (must have)
[org].arrowvpn.io:443/tcp

# NAT Traversal (strongly recommended)
[org].arrowvpn.io:80/udp
[org].arrowvpn.io:443/udp
[org].arrowvpn.io:3478/udp
[org].arrowvpn.io:5555/udp

# Relay Fallback (required if direct P2P blocked)
[org].arrowvpn.io:80/udp
[org].arrowvpn.io:443/udp
[org].arrowvpn.io:443-65535/tcp

# Or simply whitelist all ARROW VPN traffic:
*.arrowvpn.io:443/tcp
*.arrowvpn.io:80-65535/udp

Common Blocking Scenarios

1. Corporate Firewall Blocking Unknown Traffic

Symptoms:

• Device appears offline in ARROW Portal
• VPN shows “Disconnected” or “Connecting…” indefinitely
• Device works on home/mobile networks but not corporate

Cause: Egress firewall blocks outbound connections to unknown destinations

Solution: Request the IT team whitelist the NetBird endpoints listed above

2. Deep Packet Inspection (DPI) Blocking WireGuard

Symptoms:

• Initial connection appears to work, then drops
• Intermittent connectivity
• “Connection timeout” errors

Cause: DPI/IPS detects and blocks WireGuard protocol traffic

Solution:

• Request WireGuard protocol be allowed
• NetBird will fall back to relay over TCP/443 (looks like HTTPS)
• Ensure TCP relay ports are open

3. Web Proxy Intercepting Connections

Symptoms:

• SSL/TLS errors in logs
• “Certificate verification failed”
• Works when bypassing proxy

Cause: Transparent proxy intercepts and re-signs HTTPS traffic

Solution:

• Add NetBird domains to proxy bypass list
• Configure proxy exception for *.netbird.io

4. NAT/Firewall Blocking UDP

Symptoms:

• Connection works but is slow
• High latency (>200ms) even on fast networks
• “Relay” indicator in NetBird status

Cause: UDP traffic is blocked, forcing TCP relay

Solution:

• Allow UDP ports 80, 443, 3478, 5555 outbound
• Direct P2P connections (UDP) are faster than relay (TCP)

5. Captive Portal / Network Authentication

Symptoms:

• Device worked initially, stopped after network change
• “No internet” despite network connection

Cause: Network requires web authentication before allowing traffic

Solution:

• Complete captive portal authentication
• Use ethernet instead of guest WiFi when possible

Diagnostic Steps

⚠️ Remote Debugging Warning

If you are connected to the device remotely via NetBird VPN, DO NOT modify NetBird settings!

You are troubleshooting what is being blocked on the ethernet connection, not the VPN connection you’re currently using. If you restart or reconfigure NetBird while connected remotely, you will lose your connection to the device.

The diagnostic steps below are for testing ethernet connectivity to understand what the client’s network is blocking.

Use Arrow Manager VPN Connection Test (Recommended)

Arrow Manager includes a built-in VPN Connection Test tool that checks connectivity to all required NetBird endpoints:

1. Access Arrow Manager on the device
2. Navigate to the Network or Diagnostics section
3. Run the VPN Connection Test
4. Review the results to see which endpoints are reachable and which are blocked

This test will show you exactly which ports/endpoints are being blocked by the client’s firewall without requiring manual command-line troubleshooting.

Manual Diagnostic Steps

If you need to manually diagnose (via Arrow Manager terminal or SSH):

Step 1: Verify Basic Connectivity

From the ARROW device (via Arrow Manager terminal or SSH):

# Test internet connectivity
ping -c 4 8.8.8.8

# Test DNS resolution
nslookup api.netbird.io

# Test management API
curl -I https://api.netbird.io

Expected results:

• Ping should succeed
• DNS should resolve to an IP
• Curl should return HTTP 200 or 401

Step 2: Test Required Ports

# Test TCP 443 to management
nc -zv api.netbird.io 443

# Test TCP 443 to signal
nc -zv signal.netbird.io 443

# Test UDP to STUN (requires netcat with UDP support)
nc -zuv stun.netbird.io 3478

Expected: “Connection succeeded” or “open” for each

Step 3: Check NetBird Service Status

# Check service status
sudo systemctl status netbird

# View recent logs
sudo journalctl -u netbird -n 50 --no-pager

# Check connection status
sudo netbird status

Look for:

• Service should be “active (running)”
• Status should show “Connected” with peer information
• Logs should not show repeated “connection failed” messages

Step 4: Test Direct vs Relay

# Show detailed peer status
sudo netbird status -d

Check the connection type:

• direct = P2P connection established (optimal)
• relay = Traffic routing through relay (working but slower)
• disconnected = No connection (firewall blocking)

Step 5: Network Trace

If connections fail, capture what’s being blocked:

# Watch connection attempts (run as root)
sudo tcpdump -i any host api.netbird.io or host signal.netbird.io

Quick Firewall Rule Request Template

Send this to the client’s IT team:

---

Subject: Firewall Rules Required for ARROW Device

We need the following outbound connections allowed for our ARROW device to establish VPN connectivity:

VPN Endpoint (replace [org] with your organization subdomain):

• [org].arrowvpn.io

Required Ports:

• TCP 443 (management, signal, relay)
• UDP 80, 443, 3478, 5555 (NAT traversal)

Simplest Option - Whitelist all ARROW VPN traffic:

• *.arrowvpn.io on TCP 443 and UDP 80-65535

Notes:

• All connections are outbound only (no inbound required)
• Traffic is encrypted (WireGuard/TLS)
• Your specific VPN address was provided during onboarding

---

Fallback: Cellular Connection

If the client cannot or will not open required ports, ARROW devices include cellular failover:

1. The device will automatically fall back to cellular if ethernet VPN fails
2. Cellular connections bypass corporate firewalls entirely
3. This is intended as a fallback, not primary connectivity

Check Cellular First

In most cases, if ethernet VPN is blocked, the device will still show as ONLINE using the cellular connection. Check the connection type indicator in the ARROW Portal - if it shows the cellular/signal bars icon, the device is connected via cellular failover.

Device Not Online at All?

If the device shows completely offline (not even on cellular), check the following:

1. Verify Device Power

• Power Button: There is a power button on the side of the ARROW device. Press it to turn on the device.
• LED Indicator: Check for LED lights on the device - these indicate power status:
  • LED On (solid or blinking): Device has power and is running
  • LED Off: Device is not powered on - press the power button
• This is rare, but devices may be shipped powered off or accidentally turned off

2. Check Cellular Signal

If the device has power (LED on) but still not connecting via cellular:

• Weak Signal Area: The device may be in a location with poor cellular coverage
• Indoor Placement: Cellular signal can be weak in basements, server rooms, or buildings with thick walls
• Antenna Position: Ensure the device antenna (if external) is properly connected

Solutions:

• Move the device closer to a window or exterior wall
• Try a different location in the building
• Consider an external antenna extension if available

3. Fall Back to WiFi Hotspot

If cellular signal is unavailable, you can configure the device to use WiFi:

1. Access Arrow Manager via the device’s WiFi hotspot (during initial setup)
2. Configure WiFi settings to connect to an available network
3. The device will use WiFi for VPN connectivity

Note

Cellular data usage may be limited. Work with the client to resolve firewall rules for long-term deployments rather than relying on cellular or WiFi fallback.

Connection Status Indicators

In ARROW Portal

Status	Meaning
🟢 Online	VPN connected, device healthy
🟡 Degraded	Connected via relay (slow) or intermittent
🔴 Offline	No VPN connection
⚪ Unknown	Waiting for first connection

In Arrow Manager

VPN Status	Meaning
Connected	Full connectivity established
Connecting	Attempting to establish connection
Disconnected	Not connected (check firewall)
Error	Service error (check logs)

Escalation Path

If you’ve verified firewall rules are correct and connectivity still fails:

1. Collect diagnostics:

   sudo netbird status -d > /tmp/netbird-status.txt
   sudo journalctl -u netbird --since "1 hour ago" > /tmp/netbird-logs.txt

2. Note the following:

   • Device hostname (PVE-XXXX)
   • Client network configuration (proxy, DPI, etc.)
   • Time of last successful connection
   • Error messages from logs

3. Contact VTEM Labs support with the above information

Related Documentation

• VPN Management - VPN setup and configuration
• Device Management - Managing deployed devices
• Arrow Manager Troubleshooting - Device-specific issues