[GH-ISSUE #5113] Management DNS cache not auto update #10730

Open
opened 2026-08-05 01:27:05 -04:00 by saavagebueno · 3 comments
Owner

Originally created by @plusls on GitHub (Jan 15, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5113

Describe the problem

My NetBird management server is running on a machine with a non-static public IP address. I use DDNS to keep a domain name synchronized with the server’s current IP.

However, I observed that the NetBird client appears to cache the DNS resolution result of the management domain and does not automatically refresh it. When the public IP of the management server changes and the DDNS record is updated accordingly, the NetBird client continues to use the old IP address.

As a result, the client fails to reconnect to the management server after the IP change, even though the domain name correctly resolves to the new IP when queried externally (e.g., via dig or nslookup).

The client only reconnects successfully after being restarted or after some manual intervention that forces DNS re-resolution.

The domain cache start from: https://github.com/netbirdio/netbird/pull/4128

To Reproduce

Steps to reproduce the behavior:

just dig the management dns will found that:

2026-01-16T03:36:59Z TRAC client/internal/dns/handler_chain.go:167: DNS request domain=netbird.xxx.com., handlers (8):
2026-01-16T03:36:59Z TRAC client/internal/dns/handler_chain.go:175: handler matched: domain=netbird.plusls.com. -> pattern=netbird.xxx.com. wildcard=false match_subdomain=false priority=150
2026-01-16T03:36:59Z DEBG client/internal/dns/mgmt/mgmt.go:78: serving 1 cached records for domain=netbird.xxx.com.

Expected behavior

The NetBird client should periodically re-resolve the management server domain name, or at least re-resolve it on reconnection attempts, so that DDNS-based deployments continue to work correctly when the management server’s IP changes.

Are you using NetBird Cloud?

self-host

NetBird version

0.62.1

Is any other VPN software installed?

no

Debug output

To help us resolve the problem, please attach the following anonymized status output

netbird status -dA

Create and upload a debug bundle, and share the returned file key:

netbird debug for 1m -AS -U

Uploaded files are automatically deleted after 30 days.

Alternatively, create the file only and attach it here manually:

netbird debug for 1m -AS

Screenshots

If applicable, add screenshots to help explain your problem.

Additional context

Add any other context about the problem here.

Have you tried these troubleshooting steps?

  • Reviewed client troubleshooting (if applicable)
  • Checked for newer NetBird versions
  • Searched for similar issues on GitHub (including closed ones)
  • Restarted the NetBird client
  • Disabled other VPN software
  • Checked firewall settings
Originally created by @plusls on GitHub (Jan 15, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5113 **Describe the problem** My NetBird management server is running on a machine with a non-static public IP address. I use DDNS to keep a domain name synchronized with the server’s current IP. However, I observed that the NetBird client appears to cache the DNS resolution result of the management domain and does not automatically refresh it. When the public IP of the management server changes and the DDNS record is updated accordingly, the NetBird client continues to use the old IP address. As a result, the client fails to reconnect to the management server after the IP change, even though the domain name correctly resolves to the new IP when queried externally (e.g., via dig or nslookup). The client only reconnects successfully after being restarted or after some manual intervention that forces DNS re-resolution. The domain cache start from: https://github.com/netbirdio/netbird/pull/4128 **To Reproduce** Steps to reproduce the behavior: just dig the management dns will found that: ``` 2026-01-16T03:36:59Z TRAC client/internal/dns/handler_chain.go:167: DNS request domain=netbird.xxx.com., handlers (8): 2026-01-16T03:36:59Z TRAC client/internal/dns/handler_chain.go:175: handler matched: domain=netbird.plusls.com. -> pattern=netbird.xxx.com. wildcard=false match_subdomain=false priority=150 2026-01-16T03:36:59Z DEBG client/internal/dns/mgmt/mgmt.go:78: serving 1 cached records for domain=netbird.xxx.com. ``` **Expected behavior** ``` The NetBird client should periodically re-resolve the management server domain name, or at least re-resolve it on reconnection attempts, so that DDNS-based deployments continue to work correctly when the management server’s IP changes. ``` **Are you using NetBird Cloud?** self-host **NetBird version** 0.62.1 **Is any other VPN software installed?** no **Debug output** To help us resolve the problem, please attach the following anonymized status output netbird status -dA Create and upload a debug bundle, and share the returned file key: netbird debug for 1m -AS -U *Uploaded files are automatically deleted after 30 days.* Alternatively, create the file only and attach it here manually: netbird debug for 1m -AS **Screenshots** If applicable, add screenshots to help explain your problem. **Additional context** Add any other context about the problem here. **Have you tried these troubleshooting steps?** - [x] Reviewed [client troubleshooting](https://docs.netbird.io/how-to/troubleshooting-client) (if applicable) - [x] Checked for newer NetBird versions - [x] Searched for similar issues on GitHub (including closed ones) - [x] Restarted the NetBird client - [x] Disabled other VPN software - [x] Checked firewall settings
saavagebueno added the triage-needed label 2026-08-05 01:27:05 -04:00
Author
Owner

@plusls commented on GitHub (Jan 15, 2026):

I have a follow-up question regarding the current behavior.

Why does the NetBird client need to cache the DNS resolution result for the management domain? Is there a specific benefit or design consideration behind this (for example, performance optimization or avoiding frequent DNS lookups)?

In DDNS-based setups, caching the management domain’s IP can cause connectivity issues when the IP changes. Would it make more sense to always try resolving the domain name first on each (re)connection attempt, and only fall back to a cached IP if the DNS query fails?

This approach might preserve the benefits of caching while avoiding stale DNS records breaking reconnections in dynamic IP environments.

<!-- gh-comment-id:3758089956 --> @plusls commented on GitHub (Jan 15, 2026): I have a follow-up question regarding the current behavior. Why does the NetBird client need to cache the DNS resolution result for the management domain? Is there a specific benefit or design consideration behind this (for example, performance optimization or avoiding frequent DNS lookups)? In DDNS-based setups, caching the management domain’s IP can cause connectivity issues when the IP changes. Would it make more sense to always try resolving the domain name first on each (re)connection attempt, and only fall back to a cached IP if the DNS query fails? This approach might preserve the benefits of caching while avoiding stale DNS records breaking reconnections in dynamic IP environments.
Author
Owner

@ardens-jw commented on GitHub (Apr 7, 2026):

Just also wanted to add some similar experience with this, but not specifically with the management domain, with the Signal service. This has caused a loss of connectivity requiring a restart of Netbird client software (either running in Docker or Kubernetes). I echo the comments above and although I don't use Dynamic DNS, I am using a domain that is pointed at an AWS Load Balancer, whose IPs addresses I do not control and they rotate on a semi-regular basis.

<!-- gh-comment-id:4199977001 --> @ardens-jw commented on GitHub (Apr 7, 2026): Just also wanted to add some similar experience with this, but not specifically with the management domain, with the `Signal` service. This has caused a loss of connectivity requiring a restart of Netbird client software (either running in Docker or Kubernetes). I echo the comments above and although I don't use Dynamic DNS, I am using a domain that is pointed at an AWS Load Balancer, whose IPs addresses I do not control and they rotate on a semi-regular basis.
Author
Owner

@NicoJDE commented on GitHub (Aug 4, 2026):

We hit what looks like the same underlying problem during a failover game day in our self-hosted setup.

Our scenario was:

  1. Primary NetBird server went offline
  2. We failed over to a standby instance
  3. The public DNS record for the management endpoint was updated to the standby IP
  4. The client still did not recover
  5. After logging into the affected machine, DNS for the management hostname still resolved to the old IP while NetBird was running
  6. After netbird down, the hostname resolved to the new IP correctly
  7. After netbird up, the client connected to the failover instance immediately

So in our case the critical observation was:
while the NetBird client was running, the management hostname continued to resolve to the old IP; once NetBird was stopped, resolution immediately switched to the correct new IP.

From reading the recent management DNS cache changes, it seems the current behavior is no longer “never refresh”, but still “serve stale and refresh in background”. That is better than before, but for DNS-based failover it still appears problematic because the client may continue using the stale management IP during reconnect attempts.

This matters especially for:

  • DDNS setups
  • cloud IP rotation
  • DNS-based active/standby failover

If useful, I can provide a more detailed timeline / reproduction notes from the failover test.

<!-- gh-comment-id:5179088034 --> @NicoJDE commented on GitHub (Aug 4, 2026): We hit what looks like the same underlying problem during a failover game day in our self-hosted setup. Our scenario was: 1. Primary NetBird server went offline 2. We failed over to a standby instance 3. The public DNS record for the management endpoint was updated to the standby IP 4. The client still did not recover 5. After logging into the affected machine, DNS for the management hostname still resolved to the old IP while NetBird was running 6. After `netbird down`, the hostname resolved to the new IP correctly 7. After `netbird up`, the client connected to the failover instance immediately So in our case the critical observation was: while the NetBird client was running, the management hostname continued to resolve to the old IP; once NetBird was stopped, resolution immediately switched to the correct new IP. From reading the recent management DNS cache changes, it seems the current behavior is no longer “never refresh”, but still “serve stale and refresh in background”. That is better than before, but for DNS-based failover it still appears problematic because the client may continue using the stale management IP during reconnect attempts. This matters especially for: - DDNS setups - cloud IP rotation - DNS-based active/standby failover If useful, I can provide a more detailed timeline / reproduction notes from the failover test.
Sign in to join this conversation.
No Label triage-needed
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#10730