Documented NetBird-Only Access and Proxy Cluster features in reverse … (#767)

* Documented NetBird-Only Access and Proxy Cluster features in reverse proxy settings. Updated authentication methods, backend configuration guides, and cluster capability requirements. * Expanded documentation for NetBird-Only services, updated Access Control baseline behavior, added details on Direct Upstream and Proxy Cluster features, and refined cluster capability descriptions. * add private services diagrams and update auth screenshot * Document ProxyService gRPC routes and expand reverse proxy configuration details --------- Co-authored-by: TechHutTV <brandon@techhut.tv>
2026-09-28 17:59:05 +02:00 · 2026-06-05 08:16:03 -07:00
parent 4ea4552b18
commit c2ccdf43e0
17 changed files with 295 additions and 24 deletions
@@ -95,6 +95,7 @@ All reverse proxy configurations for the combined container must route the follo
 | `/ws-proxy/management*` | WebSocket | netbird-server:80 | WebSocket upgrade required |
 | `/signalexchange.SignalExchange/*` | gRPC | netbird-server:80 | HTTP/2 (h2c) required |
 | `/management.ManagementService/*` | gRPC | netbird-server:80 | HTTP/2 (h2c) required |
+| `/management.ProxyService/*` | gRPC | netbird-server:80 | HTTP/2 (h2c) required. Only needed if using the [Reverse Proxy feature](/manage/reverse-proxy). |
 | `/api/*` | HTTP | netbird-server:80 | REST API |
 | `/oauth2/*` | HTTP | netbird-server:80 | Embedded IdP |
 | `/*` | HTTP | dashboard:80 | Catch-all for dashboard |
@@ -175,7 +176,7 @@ services:
    labels:
      - traefik.enable=true
      # gRPC router (needs h2c backend for HTTP/2 cleartext)
-      - traefik.http.routers.netbird-grpc.rule=Host(`netbird.example.com`) && (PathPrefix(`/signalexchange.SignalExchange/`) || PathPrefix(`/management.ManagementService/`))
+      - traefik.http.routers.netbird-grpc.rule=Host(`netbird.example.com`) && (PathPrefix(`/signalexchange.SignalExchange/`) || PathPrefix(`/management.ManagementService/`) || PathPrefix(`/management.ProxyService/`))
      - traefik.http.routers.netbird-grpc.entrypoints=websecure
      - traefik.http.routers.netbird-grpc.tls=true
      - traefik.http.routers.netbird-grpc.tls.certresolver=letsencrypt
@@ -262,7 +263,7 @@ server {
    }

    # Native gRPC (signal + management)
-    location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService)/ {
+    location ~ ^/(signalexchange\.SignalExchange|management\.(ManagementService|ProxyService))/ {
        grpc_pass grpc://netbird_server;
        grpc_read_timeout 1d;
        grpc_send_timeout 1d;
@@ -335,7 +336,7 @@ server {
    }

    # Native gRPC (signal + management)
-    location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService)/ {
+    location ~ ^/(signalexchange\.SignalExchange|management\.(ManagementService|ProxyService))/ {
        grpc_pass grpc://netbird_server;
        grpc_read_timeout 1d;
        grpc_send_timeout 1d;
@@ -440,7 +441,7 @@ location ~ ^/(relay|ws-proxy/) {
 }

 # Native gRPC (signal + management)
-location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService)/ {
+location ~ ^/(signalexchange\.SignalExchange|management\.(ManagementService|ProxyService))/ {
    grpc_pass grpc://netbird-server:80;
    grpc_read_timeout 1d;
    grpc_send_timeout 1d;
@@ -490,7 +491,7 @@ location ~ ^/(relay|ws-proxy/) {
 }

 # Native gRPC (signal + management)
-location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService)/ {
+location ~ ^/(signalexchange\.SignalExchange|management\.(ManagementService|ProxyService))/ {
    grpc_pass grpc://127.0.0.1:8081;
    grpc_read_timeout 1d;
    grpc_send_timeout 1d;
@@ -876,6 +877,14 @@ server {
        grpc_socket_keepalive on;
    }

+    # Proxy gRPC (only needed if using the Reverse Proxy feature)
+    location /management.ProxyService/ {
+        grpc_pass grpc://netbird_management;
+        grpc_read_timeout 1d;
+        grpc_send_timeout 1d;
+        grpc_socket_keepalive on;
+    }
+
    # Embedded IdP OAuth2
    location /oauth2/ {
        proxy_pass http://netbird_management;
@@ -994,6 +1003,14 @@ server {
        grpc_socket_keepalive on;
    }

+    # Proxy gRPC (only needed if using the Reverse Proxy feature)
+    location /management.ProxyService/ {
+        grpc_pass grpc://netbird_management;
+        grpc_read_timeout 1d;
+        grpc_send_timeout 1d;
+        grpc_socket_keepalive on;
+    }
+
    # Embedded IdP OAuth2
    location /oauth2/ {
        proxy_pass http://netbird_management;
@@ -1153,6 +1170,9 @@ netbird.example.com {
    # Management gRPC
    reverse_proxy /management.ManagementService/* h2c://netbird-management:80

+    # Proxy gRPC (only needed if using the Reverse Proxy feature)
+    reverse_proxy /management.ProxyService/* h2c://netbird-management:80
+
    # Embedded IdP OAuth2
    reverse_proxy /oauth2/* netbird-management:80

@@ -1185,6 +1205,9 @@ netbird.example.com {
    # Management gRPC
    reverse_proxy /management.ManagementService/* h2c://127.0.0.1:8081

+    # Proxy gRPC (only needed if using the Reverse Proxy feature)
+    reverse_proxy /management.ProxyService/* h2c://127.0.0.1:8081
+
    # Embedded IdP OAuth2
    reverse_proxy /oauth2/* 127.0.0.1:8081

@@ -1302,6 +1325,14 @@ location /management.ManagementService/ {
    grpc_socket_keepalive on;
 }

+# gRPC for Proxy service (only needed if using the Reverse Proxy feature)
+location /management.ProxyService/ {
+    grpc_pass grpc://netbird-management:80;
+    grpc_read_timeout 1d;
+    grpc_send_timeout 1d;
+    grpc_socket_keepalive on;
+}
+
 ```

 ##### NPM running on host (Multi-Container)
@@ -1398,6 +1429,14 @@ location /management.ManagementService/ {
    grpc_socket_keepalive on;
 }

+# gRPC for Proxy service (only needed if using the Reverse Proxy feature)
+location /management.ProxyService/ {
+    grpc_pass grpc://127.0.0.1:8081;
+    grpc_read_timeout 1d;
+    grpc_send_timeout 1d;
+    grpc_socket_keepalive on;
+}
+
 ```

 ---
@@ -572,20 +572,87 @@ If your self-hosted deployment currently uses Nginx, Caddy, or another reverse p

 ## Environment variable reference

+The proxy is configured entirely through environment variables (each one maps to an equivalent CLI flag). The tables below cover every available option grouped by purpose. Only `NB_PROXY_TOKEN` and `NB_PROXY_DOMAIN` are required; the rest have sensible defaults.
+
+### Core
+
 | 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`or `netbird.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_ALLOW_INSECURE` | No | Allow an insecure (non-TLS) gRPC connection to the management server. Set to `true` only when connecting over an internal Docker network; it is a no-op for `https://` management addresses. | `false` |
+| `NB_PROXY_LOG_LEVEL` | No | Log level: `panic`, `fatal`, `error`, `warn`, `info`, `debug`, or `trace`. | `info` |
+| `NB_PROXY_DEBUG_LOGS` | No | Enable debug-level logging. **Deprecated** - use `NB_PROXY_LOG_LEVEL=debug` instead. | `false` |
+
+### TLS certificates
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_CERTIFICATE_DIRECTORY` | No | Directory where certificate files are stored (and where ACME-provisioned certificates are written). | `./certs` |
+| `NB_PROXY_CERTIFICATE_FILE` | No | TLS certificate filename within the certificate directory (static certificate mode). | `tls.crt` |
+| `NB_PROXY_CERTIFICATE_KEY_FILE` | No | TLS private key filename within the certificate directory (static certificate mode). | `tls.key` |
+| `NB_PROXY_WILDCARD_CERT_DIR` | No | Directory containing wildcard certificate pairs (`<name>.crt`/`<name>.key`). Wildcard patterns are extracted from the certificate SANs automatically. | - |
+| `NB_PROXY_CERT_LOCK_METHOD` | No | Certificate lock method for coordinating multiple replicas: `auto`, `flock`, or `k8s-lease`. | `auto` |
+
+### ACME (automatic certificates)
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
 | `NB_PROXY_ACME_CERTIFICATES` | No | Set to `true` to enable automatic TLS certificate provisioning via Let's Encrypt. | `false` |
-| `NB_PROXY_ACME_CHALLENGE_TYPE` | No | ACME challenge type: `tls-alpn-01` (port 443) or `http-01` (port 80). | `tls-alpn-01` |
-| `NB_PROXY_CERTIFICATE_FILE` | No | TLS certificate filename within the certificate directory (for static certificate mode). | `tls.crt` |
-| `NB_PROXY_CERTIFICATE_KEY_FILE` | No | TLS private key filename within the certificate directory (for static certificate mode). | `tls.key` |
-| `NB_PROXY_CERTIFICATE_DIRECTORY` | No | Directory where static certificate files are stored. | `./certs` |
-| `NB_PROXY_ALLOW_INSECURE` | No | Allow insecure (non-TLS) gRPC connection to the management server. Set to `true` when connecting over an internal Docker network. | `false` |
-| `NB_PROXY_FORWARDED_PROTO` | No | Protocol to report in the `X-Forwarded-Proto` header. Set to `https` when TLS is terminated at the proxy. | - |
-| `NB_PROXY_DEBUG_LOGS` | No | Enable debug-level logging. | `false` |
+| `NB_PROXY_ACME_CHALLENGE_TYPE` | No | ACME challenge type: `tls-alpn-01` (port 443) or `http-01` (requires port 80). | `tls-alpn-01` |
+| `NB_PROXY_ACME_ADDRESS` | No | HTTP address for ACME `http-01` challenges. Only used when the challenge type is `http-01`. | `:80` |
+| `NB_PROXY_ACME_DIRECTORY` | No | ACME directory URL. Override to use a CA other than Let's Encrypt. | Let's Encrypt production |
+| `NB_PROXY_ACME_EAB_KID` | No | ACME External Account Binding key ID, for CAs that require EAB registration. | - |
+| `NB_PROXY_ACME_EAB_HMAC_KEY` | No | ACME External Account Binding HMAC key, for CAs that require EAB registration. | - |
+
+### Networking and forwarding
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_FORWARDED_PROTO` | No | Value to report in the `X-Forwarded-Proto` header for backends: `auto`, `http`, or `https`. | `auto` |
+| `NB_PROXY_TRUSTED_PROXIES` | No | Comma-separated list of trusted upstream proxy CIDR ranges (e.g. `10.0.0.0/8,192.168.1.1`) used when parsing forwarded client IPs. | - |
+| `NB_PROXY_PROXY_PROTOCOL` | No | Enable PROXY protocol on TCP listeners to preserve client IPs behind L4 proxies. | `false` |
+| `NB_PROXY_WG_PORT` | No | WireGuard listen port (`0` = random). A fixed port only works with single-account deployments. | `0` |
+| `NB_PROXY_PRESHARED_KEY` | No | Pre-shared key for the tunnel between the proxy and peers. | - |
+| `NB_PROXY_SUPPORTS_CUSTOM_PORTS` | No | Whether the proxy can bind arbitrary ports for UDP/TCP passthrough. | `true` |
+| `NB_PROXY_REQUIRE_SUBDOMAIN` | No | Require a subdomain label in front of the cluster domain. | `false` |
+| `NB_PROXY_PRIVATE` | No | Serve private services with NetBird-Only authentication, reachable exclusively over the WireGuard tunnel (also enables per-account inbound listeners). Advanced; intended for proxies embedded in a NetBird client rather than standalone deployments. | `false` |
+| `NB_PROXY_MAX_DIAL_TIMEOUT` | No | Cap the per-service backend dial timeout (`0` = no cap), e.g. `10s`. | `0` |
+| `NB_PROXY_MAX_SESSION_IDLE_TIMEOUT` | No | Cap the per-service session idle timeout (`0` = no cap), e.g. `5m`. | `0` |
+
+### Observability and health
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_HEALTH_ADDRESS` | No | Address for the health probe endpoint (liveness/readiness/startup). | `localhost:8080` |
+| `NB_PROXY_DEBUG_ENDPOINT` | No | Enable the debug HTTP endpoint. | `false` |
+| `NB_PROXY_DEBUG_ENDPOINT_ADDRESS` | No | Address for the debug HTTP endpoint. | `localhost:8444` |
+
+### IP reputation (CrowdSec)
+
+See [Step 7: Enable CrowdSec IP reputation](#step-7-optional-enable-crowdsec-ip-reputation) for the full setup.
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_CROWDSEC_API_URL` | No | CrowdSec LAPI URL for IP reputation checks (e.g. `http://crowdsec:8080`). Empty disables CrowdSec. | - |
+| `NB_PROXY_CROWDSEC_API_KEY` | No | CrowdSec bouncer API key generated by `cscli bouncers add`. | - |
+
+### Geolocation
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_GEO_DATA_DIR` | No | Directory for the GeoLite2 MMDB file, used for geo-based access rules (auto-downloaded if missing). | `/var/lib/netbird/geolocation` |
+
+### Advanced tunnel tuning
+
+These rarely need changing; leave them unset unless you are tuning throughput.
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `NB_PROXY_PREALLOCATED_BUFFERS` | No | Cap the per-tunnel buffer pool (`0` = uncapped upstream default). Setting it below the eager-allocation floor can deadlock startup. | `0` |
+| `NB_PROXY_MAX_BATCH_SIZE` | No | Override the per-tunnel batch size, controlling how many buffers each receive/TUN worker eagerly allocates (`0` = platform default). | `0` |

 ## Troubleshooting