Step 7's config.yaml had no auth block, and the combined server exits without one
(issuer is required). The guide also enabled trafficFlow without deploying the
services that receive and store traffic events. Add both, the receiver's subject
under the traffic-events stream, its secret (the relay secret), and the
/flow.FlowService/ route on the Management load balancer.
* docs: give each relay instance its own address in the HA guide
The guide put every relay instance behind one load balancer with an
identical NB_EXPOSED_ADDRESS. Relay instances share no state, and the
address an instance announces becomes each peer's relay identity. With one
shared address, two peers whose connections land on different instances
each wait for the other on their own instance, and the relayed connection
never forms (`peer not available: ..., context deadline exceeded`), while
every peer still reports the relay as Available.
Replace the relay load balancer with two options:
1. List every instance in server.relays.addresses. Clients connect to all
of them, keep the fastest, and fail over by themselves.
2. A geo-DNS name in server.relays.addresses, with a unique, reachable
NB_EXPOSED_ADDRESS kept on every instance. Each instance then needs one
certificate valid for the shared name and its own name, supplied rather
than issued by the relay's built-in Let's Encrypt, and the DNS record
needs health checks.
Also:
- Correct the relay health check (404 page not found, not 200) and the
secret-mismatch error (invalid signature, not auth: invalid token).
- Add troubleshooting entries for both relay failure modes.
- Apply a rotated NB_AUTH_SECRET with `docker compose up -d`.
- Move the relay secret into a relay.env file with chmod 600.
- Update prerequisites, Step 4, Step 7, the Step 8 failure scenarios and the
operations section for two load balancers instead of three.
* docs: name the Management image and fix its health check and Redis errors in the HA guide
The Management replicas run the combined netbird-server-cloud image. /api/health
does not exist on it, so the load balancer check and the bring-up step now use
the OIDC discovery document, which answers while the replica serves. The Redis
troubleshooting entry now quotes the two errors the image actually prints.
* docs: use netbird.example.com for the Management domain, as the rest of the self-hosted docs do
* docs: add a tested self-hosted NATS cluster example to the HA guide
* docs: encrypt the NATS example with TLS from a private CA, and trust it in Management and Signal
* Revert "docs: encrypt the NATS example with TLS from a private CA, and trust it in Management and Signal"
This reverts commit f85a128ef3.
* docs: state that the NATS example does not configure TLS
* docs: add an external relays guide for commercial-license deployments
On NetBird Enterprise the relay's shared secret is also the traffic-flow
receiver's secret. The community guide tells readers to generate a new
secret, which on Enterprise leaves peers connected while traffic event
logging stops. Add a standalone Enterprise page that reuses the existing
secret, reads it from config.yaml, and ends with a check that the receiver
is still accepting events.
Correct the community guide:
- Relay hosts need 443/tcp, 443/udp and 3478/udp, not port 80: the relay
obtains its certificate with the TLS-ALPN-01 challenge on 443. Publish
443/udp in the compose file too, for QUIC.
- Apply a config.yaml change with `docker compose restart netbird-server`,
and a docker-compose.yml port change with `docker compose up -d`.
- Treat the config.yaml example as an addition to the server block, which
also holds auth, reverseProxy and store.
- Keep server.authSecret. Setting relays.addresses turns off the embedded
relay and STUN server, with no way to keep the embedded relay alongside.
- Relay choice is a latency race, a client can hold more than one relay
connection, and either transport can win.
- STUN status is not a failover signal, and a secret mismatch is best seen
in the relay host's log.
- Describe the startup log, the /relay response, and a certificate request
that hangs rather than errors.
- Make the proxy and supplied-certificate sections complete: the relay's
own configuration behind a proxy, what the proxy must do, what the
trusted-proxy headers affect, how to apply changes, and the pitfalls of
supplied certificates, including private CAs.
- chmod 600 relay.env, and apply later relay.env changes with
`docker compose up -d`.
List the new page under Commercial License as "External Relays (Licensed)"
and link it from the scaling guide.
* docs: clarify the receiver's log level, the firewall that restricts a published relay port, and the leftover Let's Encrypt sign
* docs: qualify the Step 1 traffic events check by the receiver's log level
* docs: cover migrated and no-traffic-flow deployments on the external relays page, and separate the two secret mismatches
* docs: name the QUIC form of the relay's secret-mismatch reason
* docs: read the active server configuration in Step 2, cover a stale receiver secret in Step 8, and separate what each receiver check proves
* Added needed account settings to the migration column and added more
dependencies.
* Export libpq when installing with homebrew.
* Update migrate-sqlite-to-postgresql.mdx
* Update docs for reverse-proxy migration.
Fixes https://github.com/netbirdio/netbird/issues/6059.
However, make sure to have someone from NetBird review before the pull
request.
* typo fixes for reverse proxy change
* Improved documentation for crowdsec.
Jack Carter