[PR #6715] [management]: Enhance relay and STUN service configuration logic #28821

Open
opened 2026-08-05 08:06:59 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/6715
Author: @josark2005
Created: 7/10/2026
Status: 🔄 Open

Base: mainHead: dev


📝 Commits (7)

  • d344109 Bump github.com/pion/dtls/v3 from 3.0.9 to 3.1.5
  • d8ea04f [management]: Enhance relay and STUN service configuration logic
  • 8d573a0 fix: clarify STUN server configuration comments in example config
  • 8c41ee8 Revert "Bump github.com/pion/dtls/v3 from 3.0.9 to 3.1.5"
  • 5d533e3 test: add unit tests for embedded relay retention and STUN additive behavior
  • 73129a0 docs: update config example comments to reflect relay/STUN additive behavior
  • 6d37c21 test: add assertions for STUN ports propagation and local STUN URIs

📊 Changes

3 files changed (+236 additions, -20 deletions)

View changed files

📝 combined/cmd/config.go (+31 -11)
combined/cmd/config_test.go (+192 -0)
📝 combined/config.yaml.example (+13 -9)

📄 Description

Describe your changes

Previously, setting server.relays.addresses unconditionally disabled the embedded relay and local STUN. This change allows the embedded relay to remain active alongside external relays when server.authSecret is set.

Changes

  • New predicate shouldStartEmbeddedRelay() — determines whether theembedded relay should start: requires authSecret to be set, and whenexternal relays are configured, authSecret must equal relays.secret

  • applyRelayDefaults() — uses the new predicate instead of a simple hasExternalRelay check; logs a warning when secrets mismatch; STUN is no longer disabled by external STUN config

  • autoConfigureClientSettings() — relay list: external and embedded addresses can coexist (embedded prepended for priority); STUN list: external and local STUN addresses can coexist (local appended)

  • config.yaml.example — comments updated to reflect the new behavior

Config behavior

authSecret relays relays.secret Embedded relay
empty any any off
set unset N/A on
set set == authSecret on
set set != authSecret off (warn)

STUN additive behavior

Previously, configuring server.stuns (external STUN servers) replaced the local STUN with the external ones. Now, external STUN addresses are sent to peers alongside local STUN addresses (configured via server.stunPorts). Local STUN is only advertised when the embedded relay is active (i.e., server.authSecret is set and matches relays.secret).

This means peers will receive more STUN candidates, improving NAT traversal success. Local STUN only starts when server.stunPorts is explicitly set (defaults to [3478]). To disable local STUN, set stunPorts to an empty list or simply omit the field:

server:
  stunPorts: []

Relay additive behavior

Previously, configuring server.relays.addresses (external relay servers) replaced the embedded relay entirely. Now, when server.authSecret is set and matches relays.secret, the embedded relay address is prepended to the external relay list sent to peers (embedded preferred for lower latency).

This means operators can add external relay capacity without losing their local relay. The embedded relay address is auto-detected from server.exposedAddress — no need to declare it in relays.addresses.

To use external relays without the embedded relay, simply omit server.authSecret:

server:
  # authSecret not set — embedded relay disabled
  relays:
    addresses:
      - "rels://relay.example.com:443"
    secret: "relay-secret"

Stack

Checklist

  • Is it a bug fix
  • Is a typo/documentation fix
  • Is a feature enhancement
  • It is a refactor
  • Created tests that fail without the change (if possible)
  • This change does not modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — OR I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See CONTRIBUTING.md.

By submitting this pull request, you confirm that you have read and agree to the terms of the Contributor License Agreement.

Documentation

Select exactly one:

  • I added/updated documentation for this change
  • Documentation is not needed for this change (explain why)

Docs PR URL (required if "docs added" is checked)

Paste the PR link from https://github.com/netbirdio/docs here:

https://github.com/netbirdio/docs/pull/845

Summary by CodeRabbit

  • New Features

    • Improved automatic configuration of embedded Relay, STUN, and signal settings.
    • Embedded Relay startup is now strictly controlled by the configured authentication secret, including when external relays are configured.
    • Embedded STUN is enabled whenever stunPorts are set, even alongside external STUN servers.
    • Client settings now prefer the embedded Relay address when applicable, while preserving external relay addresses when configured.
  • Documentation

    • Updated the example configuration to reflect the new conditional embedded Relay and STUN behavior.
  • Tests

    • Added unit tests covering embedded Relay enablement, address selection, STUN composition, and relay secret fallback.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/6715 **Author:** [@josark2005](https://github.com/josark2005) **Created:** 7/10/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `dev` --- ### 📝 Commits (7) - [`d344109`](https://github.com/netbirdio/netbird/commit/d344109f58f8870701670fee74506f450d7f0e9f) Bump github.com/pion/dtls/v3 from 3.0.9 to 3.1.5 - [`d8ea04f`](https://github.com/netbirdio/netbird/commit/d8ea04f63846660e560a400de96d564f1aa827eb) [management]: Enhance relay and STUN service configuration logic - [`8d573a0`](https://github.com/netbirdio/netbird/commit/8d573a0f49964e1ff504a21161cd640be6a4e78d) fix: clarify STUN server configuration comments in example config - [`8c41ee8`](https://github.com/netbirdio/netbird/commit/8c41ee854d499a2fb696fc09bfd1f7eb132eaee3) Revert "Bump github.com/pion/dtls/v3 from 3.0.9 to 3.1.5" - [`5d533e3`](https://github.com/netbirdio/netbird/commit/5d533e3199dc7b4b094aa0e5bf590d49bd2a8ad6) test: add unit tests for embedded relay retention and STUN additive behavior - [`73129a0`](https://github.com/netbirdio/netbird/commit/73129a099d0a98c082156b89ffeff73a8db3d03d) docs: update config example comments to reflect relay/STUN additive behavior - [`6d37c21`](https://github.com/netbirdio/netbird/commit/6d37c2157140a1892db58751b087aa704b3b6df2) test: add assertions for STUN ports propagation and local STUN URIs ### 📊 Changes **3 files changed** (+236 additions, -20 deletions) <details> <summary>View changed files</summary> 📝 `combined/cmd/config.go` (+31 -11) ➕ `combined/cmd/config_test.go` (+192 -0) 📝 `combined/config.yaml.example` (+13 -9) </details> ### 📄 Description ## Describe your changes Previously, setting `server.relays.addresses` unconditionally disabled the embedded relay and local STUN. This change allows the embedded relay to remain active alongside external relays when `server.authSecret` is set. ### Changes - **New predicate `shouldStartEmbeddedRelay()`** — determines whether theembedded relay should start: requires `authSecret` to be set, and whenexternal relays are configured, `authSecret` must equal `relays.secret` - **`applyRelayDefaults()`** — uses the new predicate instead of a simple `hasExternalRelay` check; logs a warning when secrets mismatch; STUN is no longer disabled by external STUN config - **`autoConfigureClientSettings()`** — relay list: external and embedded addresses can coexist (embedded prepended for priority); STUN list: external and local STUN addresses can coexist (local appended) - **`config.yaml.example`** — comments updated to reflect the new behavior ### Config behavior | authSecret | relays | relays.secret | Embedded relay | |---|---|---|---| | empty | any | any | off | | set | unset | N/A | on | | set | set | == authSecret | on | | set | set | != authSecret | off (warn) | ### STUN additive behavior Previously, configuring `server.stuns` (external STUN servers) replaced the local STUN with the external ones. Now, external STUN addresses are sent to peers alongside local STUN addresses (configured via `server.stunPorts`). Local STUN is only advertised when the embedded relay is active (i.e., `server.authSecret` is set and matches `relays.secret`). This means peers will receive more STUN candidates, improving NAT traversal success. Local STUN only starts when `server.stunPorts` is explicitly set (defaults to `[3478]`). To disable local STUN, set `stunPorts` to an empty list or simply omit the field: ```yaml server: stunPorts: [] ``` ### Relay additive behavior Previously, configuring `server.relays.addresses` (external relay servers) replaced the embedded relay entirely. Now, when `server.authSecret` is set and matches `relays.secret`, the embedded relay address is prepended to the external relay list sent to peers (embedded preferred for lower latency). This means operators can add external relay capacity without losing their local relay. The embedded relay address is auto-detected from `server.exposedAddress` — no need to declare it in `relays.addresses`. To use external relays without the embedded relay, simply omit `server.authSecret`: ```yaml server: # authSecret not set — embedded relay disabled relays: addresses: - "rels://relay.example.com:443" secret: "relay-secret" ``` ## Issue ticket number and link ## Stack <!-- branch-stack --> ### Checklist - [ ] Is it a bug fix - [ ] Is a typo/documentation fix - [x] Is a feature enhancement - [ ] It is a refactor - [ ] Created tests that fail without the change (if possible) - [ ] This change does **not** modify the public API, gRPC protocols, functionality behavior, CLI / service flags, or introduce a new feature — **OR** I have discussed it with the NetBird team beforehand (link the issue / Slack thread in the description). See [CONTRIBUTING.md](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#discuss-changes-with-the-netbird-team-first). > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). ## Documentation Select exactly one: - [x] I added/updated documentation for this change - [ ] Documentation is **not needed** for this change (explain why) ### Docs PR URL (required if "docs added" is checked) Paste the PR link from https://github.com/netbirdio/docs here: https://github.com/netbirdio/docs/pull/845 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Improved automatic configuration of embedded Relay, STUN, and signal settings. - Embedded Relay startup is now strictly controlled by the configured authentication secret, including when external relays are configured. - Embedded STUN is enabled whenever `stunPorts` are set, even alongside external STUN servers. - Client settings now prefer the embedded Relay address when applicable, while preserving external relay addresses when configured. - **Documentation** - Updated the example configuration to reflect the new conditional embedded Relay and STUN behavior. - **Tests** - Added unit tests covering embedded Relay enablement, address selection, STUN composition, and relay secret fallback. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 08:06:59 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#28821