sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update reverse proxy documentation for domain and DNS record changes (#648)

Browse Source 
* Update reverse proxy documentation for domain and DNS record changes

* Clarify reverse proxy domain description in migration guide

* Update domain requirement clarification in migration guide

Clarified the domain requirement for the proxy + added missing charactr afer example domain

---------

Co-authored-by: shuuri-labs <61762328+shuuri-labs@users.noreply.github.com>
This commit is contained in:
Maycon Santos
2026-03-11 19:27:45 +01:00
committed by GitHub
parent 2f6e844019
commit c413b2d00c
2 changed files with 9 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
src/pages/selfhosted/migration/enable-reverse-proxy.mdx
View File

@@ -39,18 +39,14 @@ Before starting, ensure you have:
- **Traefik** as your reverse proxy (see [Why Traefik is required](#why-traefik-is-required) above)
- **Latest NetBird images** - pull the latest version to ensure the management server and CLI support the reverse proxy feature and token creation
- **A domain for the proxy** - e.g., `proxy.example.com`. Service subdomains will be created under this domain (e.g., `myapp.proxy.example.com`)
- **Wildcard DNS capability** - ability to create a `*.proxy.example.com` DNS record pointing to your server
- **A domain for the proxy** - e.g., `proxy.example.com` or `netbird.example.com` (it can be the same domain as the NetBird server itself). Service subdomains will be created under this domain (e.g., `myapp.netbird.example.com`)
- **Wildcard DNS capability** - ability to create a `*.netbird.example.com` DNS record pointing to your server
- **Port 443 accessible** - the proxy needs this for ACME TLS-ALPN-01 challenges (certificate provisioning)
<Note>
This guide covers both the **combined container** setup (`netbirdio/netbird-server`, the default for new deployments) and the **multi-container** setup (separate `management`, `signal`, and `relay` images). Where commands or configuration differ between the two setups, both variants are shown.
</Note>
<Warning>
The proxy domain **must not** be a subdomain of your NetBird management domain. For example, if your management server is at `netbird.example.com`, do not use `proxy.netbird.example.com`. Use a separate subdomain like `proxy.example.com` instead. Using a subdomain of the management domain causes TLS and routing conflicts between the proxy and management services.
</Warning>
## Migration steps
### Step 1: Backup current configuration
@@ -190,14 +186,13 @@ The `HostSNI(*)` rule acts as a catch-all for any domain not matched by the exis
### Step 4: Set up DNS records
Create two DNS records pointing to the server running your NetBird stack - one for the base proxy domain and one wildcard for service subdomains:
Create one DNS record pointing to the server running your NetBird stack - one for the base proxy domain and one wildcard for service subdomains:
| Type | Name | Content |
|------|------|---------|
| `CNAME` | `proxy.example.com` | `netbird.example.com` |
| `CNAME` | `*.proxy.example.com` | `netbird.example.com` |
| `CNAME` | `*.netbird.example.com` | `netbird.example.com` |
The base domain record is required because a wildcard DNS record does not cover the bare domain itself. The wildcard record ensures that all service subdomains (e.g., `myapp.proxy.example.com`, `dashboard.proxy.example.com`) resolve to your server where Traefik forwards them to the proxy container.
The base domain record is required because a wildcard DNS record does not cover the bare domain itself. The wildcard record ensures that all service subdomains (e.g., `myapp.netbird.example.com`, `dashboard.netbird.example.com`) resolve to your server where Traefik forwards them to the proxy container.
### Step 5: Apply changes
@@ -404,7 +399,7 @@ If your self-hosted deployment currently uses Nginx, Caddy, or another reverse p
| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `NB_PROXY_TOKEN` | Yes | Access token generated via `netbird-server token create` (combined) or `netbird-mgmt token create` (multi-container). The proxy refuses to start without it. | - |
| `NB_PROXY_DOMAIN` | Yes | Base domain for this proxy instance (e.g., `proxy.example.com`). Determines the domain available for services. | - |
| `NB_PROXY_DOMAIN` | Yes | Base domain for this proxy instance (e.g., `proxy.example.com`or `netbird.example.com`). Determines the domain available for services. | - |
| `NB_PROXY_MANAGEMENT_ADDRESS` | No | URL of your NetBird management server. The proxy connects via gRPC to register itself. | `https://api.netbird.io:443` |
| `NB_PROXY_ADDRESS` | No | Address the proxy listens on. | `:8443` (Docker), `:443` (binary) |
| `NB_PROXY_ACME_CERTIFICATES` | No | Set to `true` to enable automatic TLS certificate provisioning via Let's Encrypt. | `false` |
@@ -482,4 +477,4 @@ docker exec -it netbird-management /go/bin/netbird-mgmt token revoke <token-id>
- [Reverse Proxy feature documentation](/manage/reverse-proxy) - full overview of services, targets, domains, and authentication
- [Custom Domains](/manage/reverse-proxy/custom-domains) - use your own domain names for reverse proxy services
- [Reverse Proxy configuration reference](/selfhosted/configuration-files#reverse-proxy-configuration) - all proxy environment variables and options
- [Self-Hosting Quickstart](/selfhosted/selfhosted-quickstart) - getting started with self-hosted NetBird
- [Self-Hosting Quickstart](/selfhosted/selfhosted-quickstart) - getting started with self-hosted NetBird

22
src/pages/selfhosted/selfhosted-quickstart.mdx
View File

@@ -14,7 +14,6 @@ This is the quickest way to try self-hosted NetBird. It should take around 5 min
- A Linux VM with at least **1CPU** and **2GB** of memory.
- The VM must be publicly accessible on **TCP ports 80 and 443**, and **UDP port 3478**.
- A **public domain** name that resolves to the VM's public IP address (e.g. `netbird.example.com`).
- *(Optional, for Proxy feature)* A **separate domain** for the proxy with a **wildcard DNS record** pointing to the same server IP. For example, if your management domain is `netbird.example.com`, add a CNAME wildcard record for `*.proxy.example.com` pointed to the same `netbird.example.com` you configured.
## Software requirements
@@ -67,23 +66,7 @@ to the internet. You control which resources are exposed through the dashboard.
Enable proxy? [y/N]:
```
If you answer `y`, the script prompts for a **proxy domain**:
```
NOTE: The proxy domain must be different from the management domain (netbird.example.com)
to avoid TLS certificate conflicts.
You also need to add two CNAME records with one wildcard for the proxy domain,
e.g. proxy.example.com and *.proxy.example.com pointing to the same server IP as netbird.example.com.
Enter the domain for the NetBird Proxy (e.g. proxy.netbird.example.com):
```
<Warning>
The proxy domain **must be different** from your NetBird management domain to avoid TLS certificate conflicts.
</Warning>
The script then automatically generates a proxy access token, creates a `proxy.env` configuration file, and starts the proxy container alongside the other services. Point a wildcard DNS record (e.g. `*.proxy.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly.
The script then automatically generates a proxy access token, creates a `proxy.env` configuration file, and starts the proxy container alongside the other services. Point a wildcard DNS record (e.g. `*.netbird.example.com`) to your server's IP address so that service subdomains resolve correctly.
### CNAME Record for Proxy Domain
@@ -92,8 +75,7 @@ For certificates to work properly, ensure you have the proper records set with y
| Type | Name | Content | Proxy status (Cloudflare) |
|------|------|---------|--------------|
| A | `netbird` | `YOUR.SERVER.IP.ADDRESS` | DNS only |
| CNAME | `proxy` | `netbird.example.com` | DNS only |
| CNAME | `*.proxy` | `netbird.example.com` | DNS only |
| CNAME | `*.netbird` | `netbird.example.com` | DNS only |
If you skipped the proxy during initial setup, you can add it later by following the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy).