sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-23 22:19:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updates for the NetBird 0.75 update (#881)

Browse Source
This commit is contained in:
PizzaLovingNerd
2026-07-24 07:43:56 -07:00
committed by GitHub
parent f6ee418c4b
commit b867aa85c8
32 changed files with 303 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/selfhosted/maintenance/scaling/high-availability.mdx
+4
View File
@@ -363,6 +363,8 @@ Common requirements for every pool:
| **Connection draining on rolling upgrade** | When you remove a backend, the LB should let in-flight gRPC streams and WebSocket connections finish before tearing them down. |
| **Generous idle timeout** | Management gRPC streams and Relay WebSocket connections can be long-lived. Set the idle timeout above your peer-sync interval. Ten to 30 minutes is a comfortable range for both. |
For the Relay frontend, configure the load balancer to strip any client-supplied `X-Real-Ip` and `X-Real-Port`, then overwrite both headers from the validated client connection. Each Relay instance must trust only the load balancer addresses that connect directly to it, using `NB_TRUSTED_PROXIES`. Without that trust, forwarded client addresses are intentionally ignored.
For the full set of paths and protocols NetBird exposes to each load balancer, see [Configuration Files Reference](/selfhosted/maintenance/configuration-files).
If you're using a managed cloud load balancer, configure the equivalent of each row above using your provider's UI or infrastructure as code. If you're using a self-hosted reverse proxy, create one backend pool per service, attach health checks, and enable HTTP/2 or WebSocket support as appropriate for each pool.
@@ -390,6 +392,7 @@ services:
- NB_LISTEN_ADDRESS=:443
- NB_EXPOSED_ADDRESS=rels://relay.example.com:443
- NB_AUTH_SECRET=<shared secret, identical on every Relay instance and on the Management pool>
- NB_TRUSTED_PROXIES=<Relay LB IP or CIDR; comma-separated if needed>
- NB_ENABLE_STUN=true
- NB_STUN_PORTS=3478
```
@@ -400,6 +403,7 @@ services:
| `NB_AUTH_SECRET` | Yes | Shared with `server.relays.secret` in every Management replica's `config.yaml`. Must be byte-identical on every Relay instance and on every Management replica. |
| `NB_LISTEN_ADDRESS` | Yes | The address the relay binds inside the container. |
| `NB_LOG_LEVEL` | No | `debug`, `info` (default), `warn`, `error`. |
| `NB_TRUSTED_PROXIES` | When preserving client addresses behind the LB | Comma-separated immediate load-balancer IPs or CIDRs allowed to supply `X-Real-Ip` and `X-Real-Port`. Both headers are required. The load balancer must strip client-supplied values and overwrite them from the validated connection. Never use broad, uncontrolled ranges. |
| `NB_ENABLE_STUN` | No | Enables the embedded STUN server on UDP. |
| `NB_STUN_PORTS` | No | STUN port (default `3478`). |
src/pages/selfhosted/maintenance/scaling/set-up-external-relays.mdx
+19
View File
@@ -42,6 +42,9 @@ NB_LISTEN_ADDRESS=:443
NB_EXPOSED_ADDRESS=rels://relay-us.example.com:443
NB_AUTH_SECRET=your-shared-secret-here
# Only when a reverse proxy or load balancer is directly in front of the relay
# NB_TRUSTED_PROXIES=10.20.0.10,10.20.1.0/24
# TLS via Let's Encrypt (automatic certificate provisioning)
NB_LETSENCRYPT_DOMAINS=relay-us.example.com
NB_LETSENCRYPT_EMAIL=admin@example.com
@@ -82,6 +85,22 @@ volumes:
relay_data:
```
## Running the Relay Behind a Proxy or Load Balancer
When a reverse proxy or load balancer terminates the Relay WebSocket connection, set `NB_TRUSTED_PROXIES` to the IP addresses or CIDRs of the proxies that connect **directly** to the relay:
```bash
NB_TRUSTED_PROXIES=10.20.0.10,10.20.1.0/24
```
The proxy must strip any client-supplied `X-Real-Ip` and `X-Real-Port`, then overwrite both headers with the address and source port from the validated client connection. The relay accepts those headers only when the immediate connection source matches the trusted list. If either header is missing, the list is empty, or the immediate source is not trusted, the relay ignores the headers and uses the direct connection address.
<Warning>
Trust only the smallest proxy IP ranges you control. Do not trust `0.0.0.0/0`, `::/0`, or a shared network where untrusted systems can connect directly to the relay and forge forwarding headers. Invalid IP or CIDR entries prevent the relay from starting.
</Warning>
The CLI equivalent is `--trusted-proxies`. Restart the relay after changing the list and check its startup logs for parsing errors.
## Alternative: TLS with Existing Certificates
If you have existing TLS certificates (e.g., from your own CA or a wildcard cert), replace the Let's Encrypt variables in `relay.env` with: