diff --git a/public/docs-static/img/manage/reverse-proxy/access-logs/access-logs-table.png b/public/docs-static/img/manage/reverse-proxy/access-logs/access-logs-table.png new file mode 100644 index 00000000..5f323d31 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/access-logs/access-logs-table.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/authentication/auth-no-auth-warning.png b/public/docs-static/img/manage/reverse-proxy/authentication/auth-no-auth-warning.png new file mode 100644 index 00000000..224f85fe Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/authentication/auth-no-auth-warning.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/authentication/auth-password-modal.png b/public/docs-static/img/manage/reverse-proxy/authentication/auth-password-modal.png new file mode 100644 index 00000000..c0e292ac Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/authentication/auth-password-modal.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/authentication/auth-pin-modal.png b/public/docs-static/img/manage/reverse-proxy/authentication/auth-pin-modal.png new file mode 100644 index 00000000..5e202da7 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/authentication/auth-pin-modal.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/authentication/auth-sso-modal.png b/public/docs-static/img/manage/reverse-proxy/authentication/auth-sso-modal.png new file mode 100644 index 00000000..25373f3a Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/authentication/auth-sso-modal.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png b/public/docs-static/img/manage/reverse-proxy/authentication/reverse-proxy-add-service-auth.png similarity index 100% rename from public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png rename to public/docs-static/img/manage/reverse-proxy/authentication/reverse-proxy-add-service-auth.png diff --git a/public/docs-static/img/manage/reverse-proxy/custom-domains-add.png b/public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-add.png similarity index 100% rename from public/docs-static/img/manage/reverse-proxy/custom-domains-add.png rename to public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-add.png diff --git a/public/docs-static/img/manage/reverse-proxy/custom-domains-start-verification.png b/public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-start-verification.png similarity index 100% rename from public/docs-static/img/manage/reverse-proxy/custom-domains-start-verification.png rename to public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-start-verification.png diff --git a/public/docs-static/img/manage/reverse-proxy/custom-domains-verification.png b/public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-verification.png similarity index 100% rename from public/docs-static/img/manage/reverse-proxy/custom-domains-verification.png rename to public/docs-static/img/manage/reverse-proxy/custom-domains/custom-domains-verification.png diff --git a/public/docs-static/img/manage/reverse-proxy/service-configuration/ha_add_addon_repository.svg b/public/docs-static/img/manage/reverse-proxy/service-configuration/ha_add_addon_repository.svg new file mode 100644 index 00000000..5779c1d9 --- /dev/null +++ b/public/docs-static/img/manage/reverse-proxy/service-configuration/ha_add_addon_repository.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/public/docs-static/img/manage/reverse-proxy/service-configuration/jellyfin-known-proxies.png b/public/docs-static/img/manage/reverse-proxy/service-configuration/jellyfin-known-proxies.png new file mode 100644 index 00000000..9c481de0 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/service-configuration/jellyfin-known-proxies.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index d3d03fa1..ac1b708a 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -287,6 +287,10 @@ export const docsNavigation = [ href: '/manage/reverse-proxy/authentication', }, { title: 'Access Logs', href: '/manage/reverse-proxy/access-logs' }, + { + title: 'Service Configuration', + href: '/manage/reverse-proxy/service-configuration', + }, { title: 'Expose from CLI', href: '/manage/reverse-proxy/expose-from-cli', diff --git a/src/pages/manage/reverse-proxy/access-logs.mdx b/src/pages/manage/reverse-proxy/access-logs.mdx index bb71db3a..c3a7b667 100644 --- a/src/pages/manage/reverse-proxy/access-logs.mdx +++ b/src/pages/manage/reverse-proxy/access-logs.mdx @@ -12,7 +12,7 @@ NetBird logs every request that passes through your reverse proxy services. Acce Access logs are available in the NetBird dashboard under **Activity** > **Proxy Events**. This view displays a table of all HTTP requests that have passed through your reverse proxy services, with filters to narrow down results by time range, status, or other fields.

- Proxy Events table showing reverse proxy access log entries + Proxy Events table showing reverse proxy access log entries

You can also retrieve access logs programmatically using the API: diff --git a/src/pages/manage/reverse-proxy/authentication.mdx b/src/pages/manage/reverse-proxy/authentication.mdx index eb0a8c0b..b6051a3a 100644 --- a/src/pages/manage/reverse-proxy/authentication.mdx +++ b/src/pages/manage/reverse-proxy/authentication.mdx @@ -8,7 +8,7 @@ export const description = NetBird Reverse Proxy supports multiple authentication methods to control who can access your exposed services. You can enable one or more methods on each service, or leave a service completely public. Authentication is configured per service in the **Authentication** tab when creating or editing a service.

- Authentication tab showing all available authentication methods + Authentication tab showing all available authentication methods

## Authentication methods @@ -22,7 +22,7 @@ SSO authentication requires users to authenticate through your identity provider You can optionally restrict access to specific **distribution groups** from your IdP. When groups are configured, only users who belong to at least one of the selected groups are allowed through after authenticating.

- SSO configuration modal with group selection + SSO configuration modal with group selection

**Key details:** @@ -43,7 +43,7 @@ You can optionally restrict access to specific **distribution groups** from your Password authentication protects a service with a shared password that you define. When a user visits the service URL, they are prompted to enter the password before they can proceed. Passwords are securely hashed using **Argon2id** on the backend - the plaintext password is never stored.

- Password configuration modal + Password configuration modal

**Key details:** @@ -60,7 +60,7 @@ Password authentication protects a service with a shared password that you defin PIN code authentication works similarly to password authentication but is limited to numeric input. When a user visits the service URL, they are prompted to enter the PIN code. PINs are securely hashed using **Argon2id** on the backend, just like passwords.

- PIN Code configuration modal + PIN Code configuration modal

**Key details:** @@ -81,7 +81,7 @@ Services can also be configured without any authentication. When no authenticati

- Warning dialog displayed when saving a service without authentication + Warning dialog displayed when saving a service without authentication

**Best for:** Public-facing websites, APIs that handle their own authentication internally, or services that are intentionally open to the internet. diff --git a/src/pages/manage/reverse-proxy/custom-domains.mdx b/src/pages/manage/reverse-proxy/custom-domains.mdx index 8719248d..f17e67b8 100644 --- a/src/pages/manage/reverse-proxy/custom-domains.mdx +++ b/src/pages/manage/reverse-proxy/custom-domains.mdx @@ -58,7 +58,7 @@ Follow these steps to add a custom domain to your account: 5. Click **Save**.

- Add Domain modal showing domain name and proxy cluster fields + Add Domain modal showing domain name and proxy cluster fields

After saving, the domain appears in your list with a **Pending Verification** status. You must complete CNAME verification before you can use the domain with a service. @@ -93,13 +93,13 @@ The exact target value depends on the proxy cluster you selected when adding the After creating the DNS record, return to the **Reverse Proxy** > **Custom Domains** page and click **Verify Domain** next to the domain.

- Domain verification modal showing CNAME record details + Domain verification modal showing CNAME record details

Confirm that the dialog reflects CNAME record you added to your domain provider and click **Start Verification**.

- Start Verification Dialog + Start Verification Dialog

NetBird performs a CNAME lookup on `*.` and verifies that it resolves to a known proxy cluster. Once verification succeeds, the domain status changes to **Active** and it becomes available in the domain selector when creating or editing services. diff --git a/src/pages/manage/reverse-proxy/index.mdx b/src/pages/manage/reverse-proxy/index.mdx index 6d052477..7ad5eb7b 100644 --- a/src/pages/manage/reverse-proxy/index.mdx +++ b/src/pages/manage/reverse-proxy/index.mdx @@ -225,6 +225,10 @@ Switch to the **Settings** tab to adjust advanced proxy behavior. - **Pass Host Header** - when enabled, the original `Host` header from the client request is forwarded to the backend service instead of the target's hostname. This is useful when the backend application needs to know the public domain it is being accessed through. - **Rewrite Redirects** - when enabled, `Location` headers in backend responses (used for HTTP redirects) are rewritten to use the public domain. This prevents users from being redirected to internal URLs that they cannot reach. + + **Backend configuration may be required.** If your backend service has a "trusted proxies", "known hosts", or "allowed networks" setting (common in Jellyfin, Home Assistant, Plex, Nextcloud, and others), you must configure it to trust the NetBird IP range. Without this, the backend may reject proxied requests or fail to read the real client IP. See [Backend Service Configuration](/manage/reverse-proxy/service-configuration) for details and per-service examples. + + ### Step 5: Create the service Click **Add Service** to create the reverse proxy service. NetBird will begin provisioning the TLS certificate and establishing the tunnel. Monitor the service status on the services list page until it shows `active`. diff --git a/src/pages/manage/reverse-proxy/service-configuration.mdx b/src/pages/manage/reverse-proxy/service-configuration.mdx new file mode 100644 index 00000000..245d0578 --- /dev/null +++ b/src/pages/manage/reverse-proxy/service-configuration.mdx @@ -0,0 +1,119 @@ +import {Note, Warning} from "@/components/mdx" + +export const description = + 'Configure backend services like Jellyfin, Home Assistant, Plex, and Nextcloud to trust the NetBird reverse proxy IP range for correct client IP detection.' + +# Backend Service Configuration + +When a backend service sits behind a reverse proxy, it sees the proxy's IP address as the client IP instead of the real user's IP. Many self-hosted applications require you to configure a list of "trusted proxies" or "known proxies" so they can correctly read the real client IP from the `X-Forwarded-For` header. + +With the NetBird Reverse Proxy, the proxy connects to your target service through a WireGuard tunnel. From the target's perspective, the source IP of incoming requests is the proxy's **NetBird IP** — an address from the `100.64.0.0/10` Carrier-Grade NAT range that NetBird uses for all peers. + + + **Do not hardcode a specific NetBird IP** (e.g., `100.64.0.47`) in your backend's trusted proxy configuration. NetBird IPs can change when the peer or service restarts, which would cause your backend to stop trusting the proxy and reject forwarded headers. + + + + **Cloud-hosted usage limits:** NetBird's cloud-hosted Reverse Proxy is provided on a shared, best-effort basis. High-volume or sustained data transfers may be subject to bandwidth limits, rate limiting, and fair-use policies under the [NetBird Terms of Service](https://netbird.io/terms). These restrictions do not apply if you [self-host NetBird](/selfhosted/selfhosted-guide). + + +## Docker Bridge Networks + +If the NetBird peer and the backend service run as containers on the **same Docker bridge network** (for example, when using the Home Assistant NetBird add-on), traffic between them does not traverse the WireGuard tunnel. In this case, the backend sees the NetBird container's **Docker bridge IP** (typically from `172.16.0.0/12`) rather than a NetBird IP. + +When this applies, add the Docker bridge subnet to your trusted proxy list **in addition to** the NetBird range: + +``` +100.64.0.0/10 +172.16.0.0/12 +``` + + + The default Docker bridge subnet is `172.17.0.0/16`, but Docker and add-on managers may assign addresses from anywhere in the `172.16.0.0/12` range. Check your Docker network configuration (`docker network inspect `) to find the exact subnet if you want a narrower entry. + + +## Recommended Solution + +Instead of specifying a single IP, configure your backend to trust the **entire NetBird CGNAT range**: + +``` +100.64.0.0/10 +``` + +This covers all possible NetBird IPs regardless of reassignment. This is safe because only authorized peers within your NetBird network can reach the target through the encrypted WireGuard tunnel — no external traffic can originate from this range. + +If the NetBird peer runs on the same Docker bridge network as the backend (see [above](#docker-bridge-networks)), also add the Docker bridge range `172.16.0.0/12`. + + + If you prefer a narrower NetBird range, you can use your account's specific network range (typically `100.64.0.0/16`). Find your account's range via the API: `GET /api/accounts/{id}` — look for the `network_range` field. However, the full `/10` range is recommended for simplicity and resilience. + + +## Service-specific Examples + +Below are configuration examples for common self-hosted applications. Configuration options may vary by version — consult each application's official documentation for the most current syntax. + +### Jellyfin + +In the Jellyfin admin dashboard: + +1. Go to **Dashboard** → **Networking**. +2. In the **Known Proxies** field, enter `100.64.0.0/10`. +3. Click **Save**. + +

+ Jellyfin Networking settings showing 100.64.0.0/10 in the Known Proxies field +

+ +This tells Jellyfin to trust forwarded headers from any NetBird IP, allowing it to see the real client IP. Additionally, Jellyfin supports adding a 'Base URL' this can be used in conjunction with setting a location while [configuring your service](https://docs.netbird.io/manage/reverse-proxy#step-2-configure-service-details) on the NetBird Reverse Proxy service. +### Home Assistant + +In your `configuration.yaml`, add or update the `http` section. You can do this through the File Editor or Studio Code Server add-on, or via the command line if you have terminal access. If you want to learn more about Home Assistant checkout our [full guide on the Knowledge Hub](https://netbird.io/knowledge-hub/home-assistant-access). + +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 100.64.0.0/10 +``` + +If you are running the [NetBird add-on](https://github.com/netbirdio/addon-netbird) (which runs as a Docker container on the same host), also add the Docker bridge range. Click the button below to get this add-on. + +[![Add NetBird add-on repository](/docs-static/img/manage/reverse-proxy/service-configuration/ha_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fglemsom%2Fhassio-netbird) + +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 100.64.0.0/10 + - 172.16.0.0/12 +``` + +Restart Home Assistant after making this change. Without `use_x_forwarded_for` and a matching `trusted_proxies` entry, Home Assistant will block requests from the reverse proxy. + +### Nextcloud + +In your Nextcloud `config/config.php`, add the NetBird range to the `trusted_proxies` array: + +```php +'trusted_proxies' => ['100.64.0.0/10'], +``` + +If you're running NextCloud AIO this should be configured automatically during setup, but if needed you can use `sudo docker exec -u 0 -it nextcloud-aio-nextcloud /bin/bash`. + +Nextcloud supports CIDR notation for IPv4 ranges. When a request arrives from a trusted proxy, Nextcloud reads the real client IP from the `X-Forwarded-For` header instead of using the proxy's IP. + +## 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 access logs — the logged client IP should be the **real user's IP**, not a `100.64.x.x` address. +3. If the backend still shows a NetBird IP, verify that **Pass Host Header** is enabled in your reverse proxy service's [Settings tab](/manage/reverse-proxy#step-4-configure-advanced-settings) and that you have restarted the backend service after changing its configuration. + +You can also monitor requests from the NetBird side using [Access Logs](/manage/reverse-proxy/access-logs). + +## Related pages + +- [Reverse Proxy Overview](/manage/reverse-proxy) — setup, concepts, and service management +- [Access Logs](/manage/reverse-proxy/access-logs) — monitor traffic to your reverse proxy services +- [How NetBird Works](/about-netbird/how-netbird-works) — details on IP assignment from the CGNAT range