Skip to content
GSISG VPN Modernization

Gotchas & Edge Cases

  1. JWT group sync shows GUIDs, not names. Entra ID groups appear as Object IDs in NetBird (self-hosted). Rename manually in dashboard after first user login.

  2. 200-group JWT limit. If a user belongs to 200+ Entra groups, the groups claim is omitted entirely. In App Registration, select “Groups assigned to the application” instead of “All groups.”

  3. events.db bloat. NetBird logs events to SQLite. With 100+ peers, events.db can grow to multiple GB. Implement a cron job to archive/truncate every 90 days.

  4. GP network monitor conflict (GitHub #5077). GlobalProtect’s virtual adapter triggers NetBird to restart WireGuard, killing TCP sessions. --network-monitor=false is the only workaround. PR #5156 is open but not merged.

  5. --network-monitor=false side effects. NetBird won’t detect Wi-Fi switches — recovery relies on WireGuard’s 25-second keepalive. Users may occasionally need netbird down && netbird up.

  6. Do NOT install NetBird on domain controllers. NetBird’s DNS management can interfere with AD DNS. Use a dedicated routing peer on the same subnet.

  7. Outbound NAT on pfSense. pfSense’s automatic NAT randomizes source ports, breaking NAT hole-punching. Add a manual outbound NAT rule with static port for the wt0 interface.

  8. AV/EDR exclusions. Add C:\Program Files\NetBird\ to exclusion lists BEFORE deployment. Bitdefender, CrowdStrike, Symantec, and ESET are known to interfere.

  9. GPO firewall rules may override NetBird. If Group Policy manages Windows Firewall, add NetBird rules to GPO before deployment.

  10. Kerberos time skew. Ensure NTP (UDP 123) is allowed through the tunnel. Kerberos fails with >5 minute clock drift.

  11. WireGuard port conflict. NetBird defaults to UDP 51820. If standalone WireGuard is also installed, use --wireguard-port 51821.

  12. On-prem detection. No native auto-disconnect when on office LAN. Use Posture Checks with Peer Network Range to block routes when on office subnet (prevents hairpin traffic).

  13. Auto-update resets settings (bug #5128). Pin version during initial deployment. Use TacticalRMM for controlled upgrades.

  14. Network Routes bypass ACL. Legacy “Network Routes” feature ignores access control policies by default. Use the newer “Networks” feature for ACL-governed routing.

  15. SSPR at Windows login screen. The SSPR link uses a temporary defaultuser1 account needing internet access to Microsoft endpoints. Works with split-tunnel (default) but may fail with full-tunnel exit node configuration.