DYNR/netbird
2
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2026-08-05 00:15:26 -04:00
Code Issues 23.5k Packages Projects Releases 10 Wiki Activity

[GH-ISSUE #5629] Link-quality-aware path selection and failover for degraded P2P connections #10863

New Issue
Open
opened 2026-08-05 01:27:31 -04:00 by saavagebueno · 0 comments
saavagebueno commented 2026-08-05 01:27:31 -04:00
Owner
Copy Link

Originally created by @nealzh on GitHub (Mar 19, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5629

Hi NetBird team,

First, thank you for building NetBird. We have been evaluating it for self-hosted deployments in complex network environments, and we think it has a strong connectivity model overall.

We would like to suggest an improvement around path selection and failover behavior.

Background

From the public documentation, NetBird’s current connection model is clearly connectivity-driven:

  • prefer direct P2P first
  • fall back to relay when direct is not possible
  • on relay, prefer QUIC and fall back to WebSocket/TCP when needed

This works well for hard failure cases, such as blocked UDP or impossible NAT traversal.

However, in many real-world networks, especially ISP or enterprise networks, UDP is often not fully blocked. Instead, it is degraded by QoS, shaping, packet loss, or jitter. In such cases:

  • direct P2P may still technically remain established
  • but the link becomes practically unusable for real workloads
  • latency increases significantly
  • packet loss becomes high
  • throughput becomes very poor
  • application requests may timeout even though the path is still shown as direct/P2P

Problem

It is currently unclear from the public docs whether NetBird performs any direct-link quality evaluation beyond basic connectivity state.

What seems to be missing is a documented mechanism for:

  • detecting degraded-but-still-alive direct P2P links
  • migrating traffic from degraded direct P2P to relay
  • switching back to direct once the path quality recovers

In practice, this matters a lot in networks where UDP is not dead, but unstable.

Suggested improvement

We would like to suggest adding link-quality-aware path selection, not only connectivity-aware fallback.

Possible improvements:

  1. Continuous direct-link quality measurement

    • packet loss
    • RTT
    • jitter
    • effective throughput
    • handshake or path-health anomalies

  2. Automatic migration from degraded direct P2P to relay

    • not only when direct is impossible
    • but also when direct quality falls below a configurable threshold

  3. Automatic recovery back to direct

    • once direct becomes healthy again
    • with hysteresis/cooldown to avoid path flapping

  4. Configurable policy modes
    For example:

    • prefer_direct_always
    • prefer_direct_unless_degraded
    • prefer_relay_for_selected_peers
    • direct-to-relay thresholds
    • relay-to-direct recovery thresholds
    • probe interval / cooldown tuning

  5. Better observability
    It would be very helpful if netbird status --detail could expose more quality-related data, such as:

    • current path quality score
    • recent packet loss
    • recent jitter / RTT trend
    • current switch reason
    • last direct→relay or relay→direct event reason

  6. Support for critical traffic profiles
    Some environments need stable low-timeout connectivity more than optimal direct performance. A policy option to prefer relay for selected peers/groups/routes would be very useful.

Why this matters

This would significantly improve NetBird’s behavior in “gray failure” environments where:

  • direct UDP is not fully broken
  • but quality is too poor for stable application traffic
  • relay over TCP/WebSocket may actually provide better real-world reliability

We believe this would make NetBird much stronger for self-hosted deployments in unstable ISP environments, enterprise networks, and mobile/CGNAT-heavy scenarios.

Thanks again for your work.

Best regards

Originally created by @nealzh on GitHub (Mar 19, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5629 Hi NetBird team, First, thank you for building NetBird. We have been evaluating it for self-hosted deployments in complex network environments, and we think it has a strong connectivity model overall. We would like to suggest an improvement around path selection and failover behavior. ## Background From the public documentation, NetBird’s current connection model is clearly connectivity-driven: * prefer direct P2P first * fall back to relay when direct is not possible * on relay, prefer QUIC and fall back to WebSocket/TCP when needed This works well for hard failure cases, such as blocked UDP or impossible NAT traversal. However, in many real-world networks, especially ISP or enterprise networks, UDP is often not fully blocked. Instead, it is degraded by QoS, shaping, packet loss, or jitter. In such cases: * direct P2P may still technically remain established * but the link becomes practically unusable for real workloads * latency increases significantly * packet loss becomes high * throughput becomes very poor * application requests may timeout even though the path is still shown as direct/P2P ## Problem It is currently unclear from the public docs whether NetBird performs any direct-link quality evaluation beyond basic connectivity state. What seems to be missing is a documented mechanism for: * detecting degraded-but-still-alive direct P2P links * migrating traffic from degraded direct P2P to relay * switching back to direct once the path quality recovers In practice, this matters a lot in networks where UDP is not dead, but unstable. ## Suggested improvement We would like to suggest adding link-quality-aware path selection, not only connectivity-aware fallback. Possible improvements: 1. Continuous direct-link quality measurement * packet loss * RTT * jitter * effective throughput * handshake or path-health anomalies 2. Automatic migration from degraded direct P2P to relay * not only when direct is impossible * but also when direct quality falls below a configurable threshold 3. Automatic recovery back to direct * once direct becomes healthy again * with hysteresis/cooldown to avoid path flapping 4. Configurable policy modes For example: * prefer_direct_always * prefer_direct_unless_degraded * prefer_relay_for_selected_peers * direct-to-relay thresholds * relay-to-direct recovery thresholds * probe interval / cooldown tuning 5. Better observability It would be very helpful if `netbird status --detail` could expose more quality-related data, such as: * current path quality score * recent packet loss * recent jitter / RTT trend * current switch reason * last direct→relay or relay→direct event reason 6. Support for critical traffic profiles Some environments need stable low-timeout connectivity more than optimal direct performance. A policy option to prefer relay for selected peers/groups/routes would be very useful. ## Why this matters This would significantly improve NetBird’s behavior in “gray failure” environments where: * direct UDP is not fully broken * but quality is too poor for stable application traffic * relay over TCP/WebSocket may actually provide better real-world reliability We believe this would make NetBird much stronger for self-hosted deployments in unstable ISP environments, enterprise networks, and mobile/CGNAT-heavy scenarios. Thanks again for your work. Best regards
saavagebueno added the feature-request label 2026-08-05 01:27:31 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
2021 Q4
2021 Q4
2021 Q4
2022 Q1
2022 Q1
2022 Q1
2022 Q1
2022 Q1
2022 Q1
accessibility
accessibility
accessibility
acl
acl
acl
agent
agent
agent
agent
agent
agent
Android
Android
Android
Android
Android
Android
api
api
api
authentik
authentik
authentik
automation
automation
automation
azure
azure
azure
battery-usage
battery-usage
battery-usage
bug
cache
cache
cache
client
client
client
client-ui
client-ui
client-ui
cloud
cloud
cloud
cloud-only
cloud-only
cloud-only
cloudflare
cloudflare
cloudflare
community
community
community
compatibility
compatibility
compatibility
config-idp
config-idp
config-idp
config-issue
config-issue
config-issue
connection
connection
connection
contribution
contribution
contribution
coturn
coturn
coturn
cross-vpn
cross-vpn
cross-vpn
dashboard
dashboard
dashboard
data-usage
data-usage
data-usage
distribution
distribution
distribution
dns
dns
dns
docker
docker
docker
documentation
documentation
documentation
duplicate
duplicate
duplicate
enhancement
enhancement
event-stream
event-stream
event-stream
feature-request
feature-request
feature-request
freebsd
freebsd
freebsd
getting-started
getting-started
getting-started
go
go
go
good first issue
good first issue
good first issue
gui
gui
gui
help wanted
help wanted
help wanted
home-assistant
home-assistant
home-assistant
idp
idp
idp
inconsistency
inconsistency
inconsistency
integration
integration
integration
integrations
integrations
integrations
ios
ios
ios
ipv6
ipv6
ipv6
jwt
jwt
jwt
k8s
k8s
k8s
keycloak
keycloak
keycloak
linux
linux
linux
login
login
login
macos
macos
macos
management-service
management-service
management-service
Medium
Medium
Medium
missing-docs
missing-docs
missing-docs
mobile
mobile
mobile
moved-internal
moved-internal
moved-internal
needs-review
needs-review
needs-review
netbird-ui
netbird-ui
netbird-ui
networking
networking
networking
new-platform
new-platform
new-platform
nginx
nginx
nginx
notification
notification
notification
okta
okta
okta
openwrt
openwrt
openwrt
P2
P2
P2
packaging
packaging
packaging
peer-management
peer-management
peer-management
peer-management
peer-management
peer-management
peer-management
peer-management
peer-management
performance
performance
performance
postgres
postgres
postgres
posture-checks
posture-checks
posture-checks
psk
psk
psk
pull-request
Mirrored from GitHub Pull Request
 question
question
question
refactor
refactor
refactor
relay
relay
relay
release
release
release
rfc
rfc
rfc
routes
routes
routes
security
security
security
security-improvement
security-improvement
security-improvement
security-related
security-related
security-related
self-hosting
self-hosting
self-hosting
server
server
server
signal
signal
signal
sleep-issue
sleep-issue
sleep-issue
ssh
ssh
ssh
ssl
ssl
ssl
status
status
status
store
store
store
synology
synology
synology
system-compatibility-issue
system-compatibility-issue
system-compatibility-issue
test-suite
test-suite
test-suite
third-party-integration
third-party-integration
third-party-integration
triage
triage
triage
triage
triage
triage
triage-needed
triage-needed
triage-needed
troubleshooting
troubleshooting
troubleshooting
UX
UX
UX
waiting-feedback
waiting-feedback
waiting-feedback
windows
windows
windows
wontfix
wontfix
wontfix
zitadel
zitadel
zitadel
No Label feature-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dynr-servers saavagebueno
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#10863
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?