From 82f3d74b5425c69349ee3b5291bbc5cec394375c Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Mon, 28 Sep 2026 16:44:43 +0200 Subject: [PATCH] docs: reverse proxy protocols, path prefix matching, active TCP services (#1007) * docs: reverse proxy protocols, path prefix matching, active TCP services Add a protocol support section: WebSocket, SSE and HTTP/2 in HTTP mode, HTTP/1.1 toward cleartext targets (no h2c), and which mode fits gRPC with and without TLS. Explain that path prefixes match as text, that the matched prefix is stripped unless Preserve Full Path is on, and how a trailing slash matches a whole segment. Add a troubleshooting entry for an active TCP service whose backend does not answer. * docs: split path matching from prefix stripping, tighten wording Move the path-matching notes after the existing overview sentence they were interrupting, and split them into matching (and the trailing-slash form) and prefix stripping (and Preserve Full Path). Merge two overlapping sentences on the upstream HTTP version, and shorten the troubleshooting cause and solution. * docs: point the active-TCP troubleshooting entry at the listener check Step 3 of the checklist is an HTTP request, which cannot confirm a TCP backend such as SSH or RDP; step 6 checks the listening socket and bind address on the target host. --- src/pages/manage/reverse-proxy/index.mdx | 15 +++++++++++++++ .../manage/reverse-proxy/troubleshooting.mdx | 14 ++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/src/pages/manage/reverse-proxy/index.mdx b/src/pages/manage/reverse-proxy/index.mdx index af4d656d..e6dc9f23 100644 --- a/src/pages/manage/reverse-proxy/index.mdx +++ b/src/pages/manage/reverse-proxy/index.mdx @@ -63,6 +63,17 @@ L4 services (TCP, UDP, TLS) listen on a dedicated port on the proxy cluster. Dep L4 services do not support browser-based authentication (SSO, password, PIN) or header authentication because there is no HTTP layer. You can use [access restrictions](/manage/reverse-proxy/authentication#access-restrictions) (IP CIDR, country, and CrowdSec rules) to protect L4 services. +### Protocol support + +HTTP services carry WebSocket connections and Server-Sent Events streams, and serve clients over HTTP/2 or HTTP/1.1. HTTP/3 is not advertised. + +Toward the backend, the proxy uses HTTP/2 only over TLS: a target with protocol `http` is always reached over HTTP/1.1, even if the backend supports HTTP/2 without TLS (h2c). This matters for gRPC, which runs over HTTP/2: + +- **gRPC backend with TLS**: use an HTTP service with an `https` target. +- **gRPC backend without TLS**: use a TCP service, which relays the connection unchanged. + +TCP services relay other TCP protocols the same way, such as SSH and RDP. + ### Targets A target defines where proxied traffic is sent within your NetBird network. Every target specifies a type and port. HTTP services additionally support path-based routing. @@ -402,6 +413,10 @@ Incoming requests are matched against the configured path prefixes and forwarded This is useful for consolidating multiple internal services under a single public domain, reducing the number of domains and TLS certificates you need to manage. +Prefixes match the request path as text, not by path segment, so a target on `/api` also receives `/api-docs`. To match a whole segment, end the path with a slash: a target on `/api/` receives `/api/x`, but not `/api-docs` or `/api` itself. + +By default, the matched prefix is removed before the request reaches the backend: `/api/x` arrives as `/x`, and `/api-docs` as `/-docs`. To keep the full path, turn on **Preserve Full Path** for the target (`path_rewrite: preserve` in the API). + ## Integration with Networks If you have already configured [Networks](/manage/networks) with resources and routing peers, you can expose a network resource directly from the Networks page. diff --git a/src/pages/manage/reverse-proxy/troubleshooting.mdx b/src/pages/manage/reverse-proxy/troubleshooting.mdx index 188e1653..dc409ce0 100644 --- a/src/pages/manage/reverse-proxy/troubleshooting.mdx +++ b/src/pages/manage/reverse-proxy/troubleshooting.mdx @@ -308,6 +308,20 @@ Once you regain access to the dashboard, you can re-enable geo-restrictions on t - Leave geo-restrictions disabled on services that the management server needs to reach internally (such as your IdP). - Use a separate network path for the IdP that doesn't pass through the reverse proxy's geo-restriction layer. +### Issue 4: TCP service is active but connections get no response + +**Symptoms**: +- A TCP service shows as active and its listen port accepts connections +- Clients connect but receive no response + +**Cause**: + +A service's status reflects the proxy's listener, not the backend: a TCP service stays active and keeps accepting connections even when nothing listens on its target port. + +**Solution**: + +Check the backend, not the service status: on the target host, confirm that the application is listening on the target port and binds to an interface the proxy can reach (step 6 of the [Quick Diagnostics Checklist](#quick-diagnostics-checklist), and Issue 2). + ## Advanced Debugging with Packet Capture If the checks above don't reveal the issue, you can use packet capture tools to verify whether traffic is actually arriving on the routing peer or target machine. This is especially useful for diagnosing routing, firewall, or NAT issues.