Backend Service Configuration

Updated November 3, 2026

For HTTP services, the NetBird reverse proxy sets X-Forwarded-For and X-Real-IP to carry the client IP to your backend. Many applications require a "trusted proxies" or "known proxies" setting before they use these headers. Configure this setting to match the source of the connection as seen by the backend, which depends on how traffic reaches it.

This page covers HTTP backends. For TCP and TLS services, see PROXY Protocol.

Identify the source IP

Check the backend's connection logs or untrusted-proxy error messages for the remote address before forwarded headers are applied. Do not use the client address from X-Forwarded-For as the trusted proxy entry.

Docker Bridge Networks

When a NetBird container forwards requests to a backend on the same Docker bridge, the backend may see the NetBird container's bridge IP. The request can still arrive at the NetBird container through a WireGuard tunnel; the final hop to the backend uses the bridge network.

Use docker network inspect <network> to check the container addresses and subnet, then match them against the backend's observed connection source. Trust the forwarding container's address when it is stable, or the specific bridge subnet when necessary. Add a NetBird range only if the backend also receives connections from that range.

Recommended Solution

Trust the smallest set of addresses or subnets that covers your proxy connections. Avoid adding the entire 100.64.0.0/10 or 172.16.0.0/12 range by default.

If the backend sees a proxy's NetBird IP, account for changes when the proxy restarts or recreates its embedded peer. You can use your account's corresponding IPv4 or IPv6 network range if other peers are prevented from connecting directly to the backend. Find the ranges under Settings → Networks: Network Range for IPv4 and IPv6 Network Range for IPv6. Alternatively, call GET /api/accounts and read settings.network_range (IPv4) and settings.network_range_v6 (IPv6) from the account object in the response array. Accounts can use a custom IPv4 range outside 100.64.0.0/10.

Service-specific Examples

In the examples below, replace <PROXY_SOURCE_IP_OR_CIDR> with the IPv4 or IPv6 address or subnet identified above. Add separate entries if more than one proxy or forwarding peer can connect to the backend, or if connections can arrive over both IPv4 and IPv6. An IPv4 trusted proxy entry does not cover an IPv6 source address.

Jellyfin

In the Jellyfin admin dashboard:

1. Go to Dashboard → Networking.
2. In the Known Proxies field, enter the proxy source addresses or CIDR ranges identified above.
3. Click Save.

Jellyfin uses this setting to decide whether to accept forwarded client IP, host, and protocol headers. See the Jellyfin reverse proxy guide.

For subpath deployments, configure Jellyfin's Base URL together with your service's path and rewrite settings.

Home Assistant

In Home Assistant 2026.8 and later, go to Settings → System → Network and find the HTTP server section. Enable Trust X-Forwarded-For and add the proxy source addresses or CIDR ranges to Trusted proxies. Saving restarts Home Assistant; confirm the settings after the restart within five minutes to avoid an automatic rollback. See the Home Assistant HTTP documentation.

On older versions, add or update the http section in configuration.yaml, then restart Home Assistant:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - "<PROXY_SOURCE_IP_OR_CIDR>"

If you use the NetBird add-on, check the source reported by Home Assistant before choosing a trusted proxy entry. It may be the add-on's container address; follow the Docker bridge guidance above.

Home Assistant rejects proxied requests unless forwarded headers are enabled and the connection source matches a trusted proxy entry. For a full setup walkthrough, see our Home Assistant guide.

Nextcloud

In your Nextcloud config/config.php, add the proxy source address or subnet to the trusted_proxies array:

'trusted_proxies' => ['<PROXY_SOURCE_IP_OR_CIDR>'],

Nextcloud accepts IPv4 and IPv6 addresses and CIDR ranges. It reads X-Forwarded-For by default for requests from trusted proxies. See the Nextcloud reverse proxy documentation.

NetBird identity headers

For HTTP services configured with NetBird-Only Access, the proxy authenticates the caller through the WireGuard tunnel and forwards the available identity information in these headers:

The proxy omits empty or unsafe header values and skips group labels containing commas or non-ASCII characters. X-NetBird-Groups is absent if no valid labels remain. These headers contain display values that can change and need not be unique; do not treat them as immutable user or group identifiers.

Example: read the user in a backend

After restricting backend access as described above, this example reads the identity headers and rejects requests without a user value:

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/me")
def me(
    user: str | None = Header(default=None, alias="X-NetBird-User"),
    groups: str | None = Header(default=None, alias="X-NetBird-Groups"),
):
    if not user:
        raise HTTPException(403, "must be accessed through a NetBird private service")
    return {
        "user": user,
        "groups": groups.split(",") if groups else [],
    }

Keep service access rules in NetBird and apply any additional application permissions separately; this example only returns the supplied identity.

Verifying your configuration

After updating your backend's trusted proxy settings:

1. Access your service through the NetBird reverse proxy URL.
2. Check the backend's resolved client IP against the client address seen by the proxy. A client using NetBird-Only Access can legitimately have a NetBird IP here.
3. If the backend reports the proxy or forwarding peer's address, check that its trusted proxy list matches the connection source, forwarded-header processing is enabled, and the backend has reloaded the configuration.

Pass Host Header controls the upstream Host header; it does not enable client IP forwarding. If a self-hosted proxy sits behind another proxy or load balancer, also check its NB_PROXY_TRUSTED_PROXIES configuration.

You can also monitor requests from the NetBird side using Access Logs.

Related pages

• Reverse Proxy Overview — setup, concepts, and service management
• Access Logs — monitor traffic to your reverse proxy services
• How NetBird Works — details on IP assignment from the CGNAT range