diff --git a/public/docs-static/img/manage/reverse-proxy/custom-domains-add.png b/public/docs-static/img/manage/reverse-proxy/custom-domains-add.png new file mode 100644 index 00000000..35eebbca Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/custom-domains-add.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/reverse-proxy-add-service-auth.png new file mode 100644 index 00000000..68f1da64 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-details.png b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-details.png new file mode 100644 index 00000000..faf238d4 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-details.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-settings.png b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-settings.png new file mode 100644 index 00000000..ebdcc717 Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-settings.png differ diff --git a/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png new file mode 100644 index 00000000..88b2a08c Binary files /dev/null and b/public/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 4d86b436..0dc688bd 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -156,6 +156,16 @@ export const docsNavigation = [ } ] }, + { + title: 'Reverse Proxy', + isOpen: false, + links: [ + { title: 'Overview', href: '/manage/reverse-proxy' }, + { title: 'Custom Domains', href: '/manage/reverse-proxy/custom-domains' }, + { title: 'Authentication', href: '/manage/reverse-proxy/authentication' }, + { title: 'Access Logs', href: '/manage/reverse-proxy/access-logs' }, + ] + }, { title: 'Network Routes', isOpen: false, @@ -320,6 +330,15 @@ export const docsNavigation = [ isOpen: false, links: [ { title: 'Configuration Files', href: '/selfhosted/configuration-files' }, + { + title: 'Scaling Your Deployment', href: '/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment', + isOpen: false, + links: [ + { title: 'Set Up External Relays', href: '/selfhosted/maintenance/scaling/set-up-external-relays' }, + { title: 'Migrate SQLite to PostgreSQL', href: '/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql' }, + { title: 'Set Up External Signal', href: '/selfhosted/maintenance/scaling/set-up-external-signal' }, + ] + }, { title: 'Backup', href: '/selfhosted/maintenance/backup' }, { title: 'Upgrade', href: '/selfhosted/maintenance/upgrade' }, { title: 'Remove', href: '/selfhosted/maintenance/remove' }, @@ -369,7 +388,7 @@ export const docsNavigation = [ isOpen: false, links: [ { title: 'Coturn to Embedded STUN', href: '/selfhosted/migration/coturn-to-stun-migration' }, - + { title: 'Enable Reverse Proxy', href: '/selfhosted/migration/enable-reverse-proxy' }, ] }, ], diff --git a/src/pages/manage/reverse-proxy/access-logs.mdx b/src/pages/manage/reverse-proxy/access-logs.mdx new file mode 100644 index 00000000..bb71db3a --- /dev/null +++ b/src/pages/manage/reverse-proxy/access-logs.mdx @@ -0,0 +1,64 @@ +import {Note} from "@/components/mdx" + +export const description = + 'Monitor and audit HTTP requests flowing through your NetBird reverse proxy services with detailed access logs.' + +# Reverse Proxy Access Logs + +NetBird logs every request that passes through your reverse proxy services. Access logs provide visibility into who is accessing your services, from where, and whether requests were allowed or denied. This is useful for auditing, debugging, and monitoring traffic to your publicly exposed services. + +## Viewing access logs + +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 +

+ +You can also retrieve access logs programmatically using the API: + +```bash +GET /api/events/proxy +``` + +## What access logs capture + +Each log entry records the following information about an HTTP request: + +| Field | Description | +|-------|-------------| +| **Timestamp** | When the request occurred | +| **Method** | HTTP method (GET, POST, PUT, DELETE, etc.) | +| **Host** | The domain the request was made to | +| **Path** | The URL path requested | +| **Status Code** | HTTP status code returned (200, 401, 403, 500, etc.) | +| **Duration** | How long the request took (in milliseconds) | +| **Source IP** | The client's IP address | +| **Auth Method** | Which authentication method was used (SSO, password, PIN, or none) | +| **User ID** | The authenticated user's ID (if SSO was used) | +| **Country** | Country of origin based on source IP geolocation | +| **City** | City of origin based on source IP geolocation | +| **Reason** | Reason for denial (if applicable) | + +## Understanding log entries + +Log entries fall into three categories based on the HTTP status code returned: + +- **Allowed requests** - Successful requests show a `2xx` status code along with the authentication method used to access the service. +- **Denied requests** - Failed authentication attempts show `401` or `403` status codes with a reason explaining why the request was denied, such as an invalid password or missing SSO session. +- **Errors** - Backend errors or proxy issues show `5xx` status codes. These typically indicate that the target service is unreachable or returned an error. + +## Use cases + +Access logs support several operational and security workflows: + +- **Security auditing** - Review who accessed sensitive services, which authentication method they used, and from which geographic locations. This helps identify unauthorized access attempts and verify that authentication policies are working as expected. +- **Debugging** - Trace failed requests to understand authentication or routing issues. The status code, duration, and reason fields help pinpoint whether problems originate from authentication configuration, target availability, or network connectivity. +- **Monitoring** - Track usage patterns across your services. Identify which services receive the most traffic, peak usage times, and unusual access patterns that may warrant investigation. +- **Compliance** - Maintain records of service access for regulatory requirements. Access logs provide an auditable trail of who accessed what, when, and from where. + +## Related pages + +- [Reverse Proxy Overview](/manage/reverse-proxy) - learn how to create and manage reverse proxy services +- [Audit Events Logging](/manage/activity) - view management-level events such as configuration changes and user activity +- [Traffic Events Logging](/manage/activity/traffic-events-logging) - monitor network-level traffic events across your NetBird mesh diff --git a/src/pages/manage/reverse-proxy/authentication.mdx b/src/pages/manage/reverse-proxy/authentication.mdx new file mode 100644 index 00000000..eb0a8c0b --- /dev/null +++ b/src/pages/manage/reverse-proxy/authentication.mdx @@ -0,0 +1,163 @@ +import {Note} from "@/components/mdx" + +export const description = + 'Configure SSO, password, and PIN authentication methods for NetBird Reverse Proxy services to control who can access your exposed applications.' + +# Reverse Proxy Authentication + +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 methods + +NetBird offers three authentication methods, each suited to different access patterns. You can enable any combination of them on a single service. + +### SSO (Single Sign-On) + +SSO authentication requires users to authenticate through your identity provider (IdP) using OIDC before they can access the service. When a user visits the service URL, they are redirected to your IdP login page. After successful authentication, they are granted access to the service. + +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 +

+ +**Key details:** + +- Users authenticate via your existing identity provider (OIDC) +- Sessions last **24 hours** before re-authentication is required +- Optionally restrict access to specific distribution groups synced from your IdP +- When no groups are selected, any authenticated user in your organization can access the service + + + **Self-hosted deployments:** SSO authentication uses whichever OIDC provider is configured in your management server. If you use the built-in embedded IdP, SSO works automatically. If you use an external identity provider (Auth0, Okta, Keycloak, etc.) without the embedded IdP, you must register the reverse proxy callback URL with your IdP before SSO will work. See the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy#configure-sso-for-external-identity-providers) for step-by-step instructions. + + +**Best for:** Team services where you want to leverage existing identity management, internal tools that require user-level accountability, and services where you need group-based access control. + +### Password + +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 +

+ +**Key details:** + +- Set a shared password when configuring the service +- Users must enter the correct password to access the service +- Passwords are hashed with Argon2id before being stored +- Sessions last **24 hours** before re-authentication is required + +**Best for:** Simple shared access to internal tools, staging environments, or services shared with external partners who do not have accounts in your identity provider. + +### PIN Code + +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 +

+ +**Key details:** + +- Set a numeric PIN code when configuring the service +- Users must enter the correct PIN to access the service +- PINs are hashed with Argon2id before being stored +- Sessions last **24 hours** before re-authentication is required + +**Best for:** Quick access scenarios, kiosk-style interfaces, or situations where a simple numeric code is easier to share than a full password. + +### No authentication (public access) + +Services can also be configured without any authentication. When no authentication method is enabled, anyone with the service URL can access it without any restrictions. + + + When you save a service with no authentication configured, the dashboard displays a warning: **"This service will be publicly accessible to everyone on the internet without any restrictions."** You must confirm before the service is saved. Make sure this is intentional before proceeding. + + +

+ 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. + +## Combining authentication methods + +You can enable multiple authentication methods on a single service simultaneously. When more than one method is active, users can authenticate using **any** of the enabled methods - they choose which one to use when accessing the service. + +For example, you could enable both **SSO** and **Password** on the same service. Team members who have accounts in your identity provider can authenticate with SSO, while external partners or contractors can use a shared password. This gives you flexibility without requiring everyone to be in your IdP. + +Common combinations include: + +| Combination | Use case | +|-------------|----------| +| **SSO + Password** | Team members use SSO; external collaborators use a shared password | +| **SSO + PIN Code** | Team members use SSO; quick access via PIN for specific scenarios | +| **Password + PIN Code** | Different shared credentials for different groups of users | +| **SSO + Password + PIN Code** | Maximum flexibility with all methods available | + +## Configuring authentication + +All authentication settings are managed in the **Authentication** tab of the service creation or edit modal. Navigate to **Reverse Proxy** > **Services**, then either click **Add Service** to create a new service or click an existing service to edit it. + +### Setting up SSO + +1. Open the service modal (create or edit). +2. Switch to the **Authentication** tab. +3. Click **SSO (Single Sign-On)**. +4. Enable SSO using the toggle. +5. Optionally, select one or more **distribution groups** to restrict access to specific users. If no groups are selected, all authenticated users in your organization can access the service. +6. Click **Save** (or **Save Changes** when editing). + + + Distribution groups are synced from your identity provider. If you do not see the groups you expect, check your [IdP sync configuration](/manage/team/idp-sync) or [Single Sign-On setup](/manage/team/single-sign-on). + + +### Setting up a password + +1. Open the service modal (create or edit). +2. Switch to the **Authentication** tab. +3. Click **Password**. +4. Enter a password in the input field. +5. Click **Save** (or **Save Changes** when editing). + +### Setting up a PIN code + +1. Open the service modal (create or edit). +2. Switch to the **Authentication** tab. +3. Click **PIN Code**. +4. Enter a numeric PIN in the input field. +5. Click **Save** (or **Save Changes** when editing). + +### Removing authentication + +To remove an authentication method from a service: + +1. Open the service modal by clicking the service in the services list. +2. Switch to the **Authentication** tab. +3. Click on the authentication method you want to remove. +4. Use the **Remove** option to disable it. +5. Click **Save Changes**. + +If you remove all authentication methods, the service becomes publicly accessible. The dashboard will display a warning before saving, as described in the [No authentication](#no-authentication-public-access) section above. + +## Session management + +Authenticated sessions for reverse proxy services are managed using JWT (JSON Web Token) technology. Here is how sessions work: + +- **Token signing:** Sessions use JWT tokens signed with **Ed25519** key pairs. Each service has its own unique key pair, ensuring that tokens for one service cannot be used to access another. +- **Session duration:** Authenticated sessions expire after **24 hours**. After expiry, users must re-authenticate using whichever method they originally used. +- **Scope:** Sessions are scoped to individual services. Authenticating with one service does not grant access to other services, even if they use the same authentication method. + +## Related pages + +- [Reverse Proxy Overview](/manage/reverse-proxy) - learn how the reverse proxy feature works and create your first service +- [Custom Domains](/manage/reverse-proxy/custom-domains) - configure your own domain names for reverse proxy services +- [Access Logs](/manage/reverse-proxy/access-logs) - monitor and audit traffic to your reverse proxy services +- [Single Sign-On](/manage/team/single-sign-on) - configure your identity provider for SSO across NetBird +- [Provision Users and Groups](/manage/team/idp-sync) - sync users and groups from your identity provider diff --git a/src/pages/manage/reverse-proxy/custom-domains.mdx b/src/pages/manage/reverse-proxy/custom-domains.mdx new file mode 100644 index 00000000..b5e027b2 --- /dev/null +++ b/src/pages/manage/reverse-proxy/custom-domains.mdx @@ -0,0 +1,166 @@ +import {Note} from "@/components/mdx" + +export const description = + 'Configure free and custom domains for NetBird Reverse Proxy services, including CNAME validation and DNS setup.' + +# Custom Domains + +When you create a reverse proxy service, you need to assign it a domain. NetBird provides built-in domains that are automatically available for every account, and also supports custom domains where you bring your own domain name. This page explains how both types work and walks you through adding and validating a custom domain. + +## Built-in domains + +Every NetBird deployment comes with built-in domains that you can use immediately - no DNS configuration required. The format and labeling of these domains differ between cloud and self-hosted deployments. + +### Cloud deployments (Free domains) + +Cloud accounts receive free domains in the format: + +``` +{subdomain}.{nonce}.{cluster}.proxy.netbird.io +``` + +For example: `myapp.abc123.eu.proxy.netbird.io` where `myapp` is your chosen subdomain, `abc123` is a nonce unique to your account, and `eu` is the proxy cluster region. + +NetBird operates multiple proxy clusters in different regions, and your available free domains correspond to these clusters. In the domain selector, free domains appear with a **Free** badge. + +### Self-hosted deployments (Cluster domains) + +Self-hosted deployments provide cluster domains in the format: + +``` +{subdomain}.{proxy-domain} +``` + +For example: `myapp.proxy.mycompany.com` where `myapp` is your chosen subdomain and `proxy.mycompany.com` is the domain configured on your proxy instance(s) via the `NB_PROXY_DOMAIN` environment variable. + +There is no nonce in self-hosted domains. In the domain selector, these domains appear with a **Cluster** badge. + +### How built-in domains are derived + +In both deployment types, built-in domains are dynamically derived from the proxy instances currently connected to the management server. They are not pre-provisioned - they reflect whichever proxy servers are actively registered via gRPC. If a proxy instance disconnects, its associated domain may no longer appear in the selector until the instance reconnects. + +Built-in domains are a quick way to get started. They receive automatic TLS certificates and work the same as custom domains in every other respect. + +## Custom domains + +Custom domains let you use your own domain name (e.g., `app.example.com`) for reverse proxy services. Custom domains work identically in both cloud and self-hosted deployments. Before a custom domain can be used, you must validate ownership by creating a CNAME record in your DNS provider. + +To manage custom domains, navigate to **Reverse Proxy** > **Custom Domains** in the NetBird dashboard. + +## Adding a custom domain + +Follow these steps to add a custom domain to your account: + +1. Navigate to **Reverse Proxy** > **Custom Domains** in the NetBird dashboard. +2. Click **Add Domain**. +3. Enter your domain name (e.g., `proxy.example.com`). +4. Select the target **proxy cluster** that will handle traffic for this domain. +5. Click **Save**. + +

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

+ +After saving, the domain appears in your list with an **unvalidated** status. You must complete CNAME validation before you can use the domain with a service. + +## Validating a custom domain + +To prove that you own the domain, NetBird requires you to create a specific CNAME record in your DNS provider. + +### Step 1: Create the CNAME record + +In your DNS provider, create a CNAME record for the `validation` subdomain of your custom domain, pointing to the proxy cluster address. The CNAME target depends on your deployment type: + +- **Cloud deployments** - point to a NetBird-hosted cluster address (e.g., `eu.proxy.netbird.io`) +- **Self-hosted deployments** - point to your own proxy URL (e.g., `proxy.mycompany.com`) + +For example, on a cloud deployment: + +| Record Type | Name | Value | +|-------------|------|-------| +| `CNAME` | `validation.proxy.example.com` | `eu.proxy.netbird.io` | + +On a self-hosted deployment: + +| Record Type | Name | Value | +|-------------|------|-------| +| `CNAME` | `validation.proxy.example.com` | `proxy.mycompany.com` | + +The exact target value depends on the proxy cluster you selected when adding the domain. The NetBird dashboard displays the required CNAME target after you save the domain. + +### Step 2: Validate in the dashboard + +After creating the DNS record, return to the **Reverse Proxy** > **Custom Domains** page and click **Validate** next to the domain. + +

+ Domain validation status showing CNAME record details +

+ +NetBird performs a CNAME lookup on `validation.` and verifies that it resolves to a known proxy cluster. Once validation succeeds, the domain status changes to **validated** and it becomes available in the domain selector when creating or editing services. + + + DNS changes can take time to propagate. If validation fails immediately after creating the CNAME record, wait a few minutes and try again. In some cases, DNS propagation can take up to 48 hours depending on your provider and TTL settings. + + +## Managing custom domains + +The **Custom Domains** page lists all domains associated with your account, including both built-in and custom domains. + +### Viewing domains + +The domain list shows each domain along with its type (Free, Cluster, or Custom), the associated proxy cluster, and the current validation status. + +### Re-validating a domain + +If a custom domain becomes unvalidated - for example, after a DNS configuration change - you can click **Validate** to trigger a new CNAME lookup. + +### Deleting a custom domain + +To remove a custom domain, click the delete action next to the domain in the list. Deleting a custom domain removes it from your account and makes it unavailable for any new services. Built-in domains (Free or Cluster) cannot be deleted. + + + Before deleting a custom domain, make sure no active services are using it. Services referencing a deleted domain will no longer route traffic correctly. + + +## Using domains with services + +When you create or edit a reverse proxy service, the domain selector presents all available domains: + +- All **validated** custom domains +- All built-in domains - **Free** domains (cloud) or **Cluster** domains (self-hosted) + +To assign a domain to a service, enter a **subdomain** on the left side of the selector and choose a **base domain** on the right side. The full public URL for your service is the combination of both: + +``` +{subdomain}.{base-domain} +``` + +For example, if you enter `dashboard` as the subdomain and select `proxy.example.com` as the base domain, the service is accessible at `dashboard.proxy.example.com`. + +All domain types receive automatic TLS certificates managed by the proxy. + +## Troubleshooting + +### Domain shows as unvalidated + +Verify that the CNAME record for `validation.` is correctly configured and points to the right proxy cluster address. For cloud deployments, this is a NetBird-hosted address (e.g., `eu.proxy.netbird.io`). For self-hosted deployments, this is your own proxy URL (e.g., `proxy.mycompany.com`). Use a DNS lookup tool to confirm the record has propagated: + +```bash +dig CNAME validation.proxy.example.com +``` + +If the record does not appear, check your DNS provider for typos or wait for propagation to complete. + +### CNAME pointing to the wrong cluster + +The CNAME record must resolve to one of your available proxy clusters. If you selected a different cluster when adding the domain, the validation lookup will fail. Verify the expected target value on the Custom Domains page in the dashboard and update your DNS record accordingly. + +### Domain already in use + +Each custom domain must be unique across all NetBird accounts. If you receive an error that the domain is already in use, it may be registered by another account. Verify that you are entering the correct domain name. If you believe this is an error, contact [NetBird support](/slack-url). + +## Related pages + +- [Reverse Proxy Overview](/manage/reverse-proxy) - learn how the reverse proxy feature works +- [Authentication](/manage/reverse-proxy/authentication) - configure SSO, password, and PIN authentication for services +- [Access Logs](/manage/reverse-proxy/access-logs) - monitor traffic to your reverse proxy services diff --git a/src/pages/manage/reverse-proxy/index.mdx b/src/pages/manage/reverse-proxy/index.mdx new file mode 100644 index 00000000..fab42641 --- /dev/null +++ b/src/pages/manage/reverse-proxy/index.mdx @@ -0,0 +1,281 @@ +import {Note} from "@/components/mdx" + +export const description = + 'Expose internal services to the public internet with automatic TLS, authentication, and traffic routing through the NetBird mesh network.' + +# Reverse Proxy + +NetBird Reverse Proxy lets you expose internal services running on peers or behind network resources to the public internet. NetBird handles TLS termination, optional authentication, and proxies incoming traffic through the WireGuard mesh to reach the target service - all without opening ports or configuring firewalls on your internal machines. + + + **Availability:** Reverse Proxy is currently only available for **self-hosted** deployments and is currently in **beta**. **Cloud** support is coming soon. + + + **Self-hosted requirement:** Self-hosted deployments **must** use [Traefik](/selfhosted/reverse-proxy) as their reverse proxy. Traefik is the only supported reverse proxy that provides TLS passthrough, which is required for the Reverse Proxy feature to function correctly. + + +## How it works + +When you create a reverse proxy service, NetBird provisions a public domain with an automatic TLS certificate. Incoming HTTPS requests to that domain are terminated at the NetBird proxy cluster, then forwarded through an encrypted WireGuard tunnel to the target peer or network resource running your application. The target service only needs to be reachable within your NetBird network - it does not need a public IP address or open ports. + +You can optionally require authentication (SSO via your configured IdP, password, or PIN) before users can reach the service, ensuring that even publicly accessible URLs remain protected. + +## Concepts + +### Services + +A service is the core configuration unit of the Reverse Proxy. Each service maps a public domain to one or more internal targets and defines how traffic is authenticated and forwarded. A service consists of: + +- **Domain** - the public URL where the service is reachable +- **Targets** - one or more backend destinations that handle incoming requests +- **Authentication** - optional SSO, password, or PIN protection +- **Settings** - advanced options for host header forwarding and redirect rewriting +- **Enabled/Disabled toggle** - turn the service on or off without deleting it + +### Targets + +A target defines where proxied traffic is sent within your NetBird network. Each service can have multiple targets for path-based routing. Every target specifies a type, protocol, port, and optional path. + +| Type | Description | How to select | +|------|-------------|---------------| +| **Peer** | A machine running the NetBird agent directly | Select from the peer list | +| **Host** | A network resource identified by an IP address | Select from your network resources | +| **Domain** | A network resource identified by a domain name | Select from your network resources | +| **Subnet** | A network resource within a CIDR range | Select from your network resources, then specify an IP within the range | + +Each target also has the following properties: + +- **Path** (optional) - a URL path prefix for path-based routing (e.g., `/api`). See [Path-based routing](#path-based-routing) below. +- **Protocol** - `HTTP` or `HTTPS`, depending on what the backend service speaks +- **Port** - the port on the target machine (defaults to `80` for HTTP, `443` for HTTPS) +- **Enabled/Disabled toggle** - individually enable or disable targets without removing them + +### Domains + +Every service needs a domain. The available domain types depend on whether you are using NetBird Cloud or a self-hosted deployment. + +**Cloud deployments** provide free domains in the format: + +``` +{subdomain}.{nonce}.{cluster}.proxy.netbird.io +``` + +For example: `myapp.abc123.eu.proxy.netbird.io` where `myapp` is your chosen subdomain, `abc123` is a nonce unique to your account, and `eu` is the proxy cluster region. These domains appear in the domain selector with a **Free** badge and are available immediately with no additional configuration. + +**Self-hosted deployments** provide cluster domains in the format: + +``` +{subdomain}.{proxy-domain} +``` + +For example: `myapp.proxy.mycompany.com` where `myapp` is your chosen subdomain and `proxy.mycompany.com` is the domain configured on your proxy instance(s) via the `NB_PROXY_DOMAIN` environment variable. These domains appear in the domain selector with a **Cluster** badge. + +In both deployment types, the available domains are dynamically derived from the proxy instances currently connected to the management server. They are not pre-provisioned - they reflect whichever proxy servers are actively registered. + +**Custom domains** work identically in both cloud and self-hosted deployments. You can use your own domain name (e.g., `app.example.com`) by creating a CNAME record that points to your proxy cluster address. See [Custom Domains](/manage/reverse-proxy/custom-domains) for setup instructions. + +All domain types receive automatic TLS certificates managed by the proxy. + +### Authentication + +You can protect a service with one or more authentication methods. When multiple methods are enabled, users can choose which one to use when accessing the service. + +| Method | Description | +|--------|-------------| +| **SSO (Single Sign-On)** | Authenticate via your identity provider using OIDC. You can optionally restrict access to specific user groups. | +| **Password** | Protect with a shared password that you define when configuring the service. | +| **PIN Code** | Protect with a numeric PIN code. | +| **No authentication** | The service is publicly accessible without any authentication. | + + + If you save a service with no authentication configured, the dashboard will display a warning. Public services are accessible to anyone on the internet who knows the URL. + + +For detailed configuration instructions, see [Authentication](/manage/reverse-proxy/authentication). + +### Service statuses + +After creating a service, it progresses through several statuses as NetBird provisions the domain and establishes connectivity: + +| Status | Meaning | +|--------|---------| +| `pending` | The service has been created and is being provisioned. | +| `certificate_pending` | A TLS certificate is being issued for the domain. This applies when the proxy uses ACME (Let's Encrypt) to automatically provision certificates. | +| `active` | The service is live and routing traffic to its targets. | +| `tunnel_not_created` | The proxy cluster has not yet established a WireGuard tunnel to the target. | +| `certificate_failed` | TLS certificate issuance failed. If the proxy uses ACME, verify that the ACME challenge port is accessible (port 443 for `tls-alpn-01`, port 80 for `http-01`) and that the domain resolves correctly. For static certificates, check that the certificate and key files are valid. | +| `error` | A generic error occurred. Check the service configuration and target availability. | + +## Self-hosted proxy setup + +Self-hosted deployments require a separate NetBird proxy instance (`netbirdio/netbird-proxy`) that connects to your management server via gRPC and handles TLS termination and traffic forwarding for your reverse proxy services. + + +**Already set up?** If you deployed NetBird using the setup script (`getting-started.sh`) starting from **v0.65.0** and selected the **built-in Traefik** option, the proxy container is already included in your Docker Compose stack. You can skip straight to [creating your first service](#quick-start). + + +**Existing deployments** - If you have an existing self-hosted deployment and want to add the proxy, follow the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy). It covers generating an access token, adding the proxy container with Traefik TLS passthrough labels, setting up wildcard DNS, and verifying the setup. + +### TLS certificate configuration + +The proxy supports two modes for TLS certificate management: + +**ACME mode (Let's Encrypt)** - The proxy automatically provisions TLS certificates for each domain using Let's Encrypt. Enable this mode with: + +| Environment variable | Description | +|---------------------|-------------| +| `NB_PROXY_ACME_CERTIFICATES` | Set to `true` to enable automatic certificate provisioning. | +| `NB_PROXY_ACME_CHALLENGE_TYPE` | ACME challenge type (default: `tls-alpn-01`). The `tls-alpn-01` challenge uses port 443 and does not require port 80. Alternatively, set to `http-01` which requires port 80 to be accessible. | + +When a certificate is successfully issued, the proxy notifies the management server and the service status changes to `active`. + +**Static certificate mode** - Provide your own certificate and key files. This is useful for wildcard certificates or certificates from a corporate CA. Configure with: + +| Environment variable | Description | +|---------------------|-------------| +| `NB_PROXY_CERTIFICATE_FILE` | TLS certificate filename within the certificate directory (default: `tls.crt`) | +| `NB_PROXY_CERTIFICATE_KEY_FILE` | TLS private key filename within the certificate directory (default: `tls.key`) | +| `NB_PROXY_CERTIFICATE_DIRECTORY` | Directory where certificate files are stored (default: `./certs`) | + +Static certificates support hot-reload through file watching. When the certificate or key file changes on disk, the proxy picks up the new files automatically without requiring a restart. + +### High availability + +Multiple proxy instances configured with the same `NB_PROXY_DOMAIN` value form a single proxy cluster. This provides high availability - if one instance goes down, the remaining instances in the cluster continue serving traffic. Each instance independently connects to the management server via gRPC and registers under the shared cluster address. + +### Traefik requirement + +Self-hosted deployments must use [Traefik](/selfhosted/reverse-proxy) as the reverse proxy in front of the NetBird management server. Traefik is required because it supports TLS passthrough, which allows the NetBird proxy to handle TLS termination directly. Other reverse proxies that do not support TLS passthrough are not compatible with this feature. + +## Prerequisites + +Before creating a reverse proxy service, make sure you have: + +- At least one **peer** connected to your NetBird network, OR at least one **network** with resources and routing peers configured. See [Networks](/manage/networks) for details. +- A domain to use. Free (cloud) or cluster (self-hosted) domains are available automatically, or you can [add a custom domain](/manage/reverse-proxy/custom-domains). +- **Self-hosted only:** At least one proxy instance deployed and connected to your management server. See [Self-hosted proxy setup](#self-hosted-proxy-setup) above, or follow the [Enable Reverse Proxy migration guide](/selfhosted/migration/enable-reverse-proxy) to add it to an existing deployment. +- Access to a NetBird account with the 'Services' permission module ('Network Admin' role or higher). + +## Quick start + +Follow these steps to create your first reverse proxy service and expose an internal application to the internet. + +### Step 1: Open the Reverse Proxy page + +Navigate to **Reverse Proxy** > **Services** in the NetBird dashboard and click **Add Service**. + +### Step 2: Configure service details + +In the **Details** tab: + +1. Enter a **subdomain** for your service (e.g., `myapp`). +2. Select a **base domain**. Cloud users see domains with a **Free** badge (e.g., `abc123.eu.proxy.netbird.io`). Self-hosted users see domains with a **Cluster** badge (e.g., `proxy.mycompany.com`, based on their deployed proxy instances). You can also select a custom domain you have already configured. +3. Click **Add Target** to define where traffic should be sent. + +

+ Add Service modal showing the Details tab +

+ +4. In the target configuration, select the **type** (Peer, Host, Domain, or Subnet), then choose the specific peer or resource. +5. Set the **protocol** (HTTP or HTTPS) and **port** for the target. +6. Optionally, enter a **path** if you are using path-based routing. + +

+ Add Target configuration modal +

+ +You can add multiple targets to route different URL paths to different backend services. + +### Step 3: Configure authentication + +Switch to the **Authentication** tab to configure how users are authenticated before reaching your service. + +

+ Add Service modal showing the Authentication tab +

+ +- Enable **SSO** to require users to authenticate through your identity provider. Optionally restrict access to specific groups. +- Enable **Password** and set a shared password. +- Enable **PIN Code** and set a numeric code. +- Leave all methods disabled for public (unauthenticated) access. + + + You can enable multiple authentication methods simultaneously. Users will be able to choose their preferred method when accessing the service. + + +### Step 4: Configure advanced settings + +Switch to the **Settings** tab to adjust advanced proxy behavior. + +

+ Add Service modal showing the Settings tab +

+ +- **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. + +### 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`. + +## Managing services + +### Edit a service + +Click on any service in the services list to open the edit modal. Make your changes across the Details, Authentication, or Settings tabs, then click **Save Changes**. + +### Enable or disable a service + +Toggle the service on or off using the enabled/disabled switch. Disabling a service stops routing traffic to it without deleting the configuration, allowing you to quickly re-enable it later. + +### Delete a service + +Delete a service to permanently remove it along with its domain and TLS certificate. This action cannot be undone. + +### Manage targets + +Within a service, you can: + +- **Add targets** - click **Add Target** to route traffic to additional backend services +- **Remove targets** - remove a target to stop routing traffic to that backend +- **Enable or disable targets** - toggle individual targets on or off without removing them from the service + +## Path-based routing + +When a service has multiple targets, you can assign each target a unique path prefix to route different URL paths to different backends. For example: + +| Path | Target | Description | +|------|--------|-------------| +| `/` | Peer A (port 3000) | Main web application | +| `/api` | Peer B (port 8080) | API service | +| `/docs` | Resource C (port 80) | Documentation server | + +Incoming requests are matched against the configured path prefixes and forwarded to the corresponding target. Each path must be unique within a service. + +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. + +## 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. + +Click the **Expose Service** button on any resource to open the reverse proxy creation modal with that resource pre-populated as a target. This provides a quick way to make an existing internal resource available on the public internet. + +The Networks page also displays a badge on each resource indicating how many reverse proxy services reference it, giving you visibility into which resources are publicly exposed. + +## Related pages + +- [Custom Domains](/manage/reverse-proxy/custom-domains) - configure your own domain names for reverse proxy services +- [Authentication](/manage/reverse-proxy/authentication) - detailed guide on SSO, password, and PIN authentication options +- [Access Logs](/manage/reverse-proxy/access-logs) - monitor and audit traffic to your reverse proxy services +- [Networks](/manage/networks) - configure internal networks and resources +- [Access Control](/manage/access-control/manage-network-access) - manage policies that control access to your network + +## Get started +
+ +
+ +- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) +- Follow us [on X](https://x.com/netbird) +- Join our [Slack Channel](/slack-url) +- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub diff --git a/src/pages/selfhosted/configuration-files.mdx b/src/pages/selfhosted/configuration-files.mdx index 2457f91d..b3e6a551 100644 --- a/src/pages/selfhosted/configuration-files.mdx +++ b/src/pages/selfhosted/configuration-files.mdx @@ -15,11 +15,9 @@ A standard NetBird self-hosted deployment uses the following configuration files | File | Purpose | |------|---------| -| `docker-compose.yml` | Defines all NetBird services (dashboard, management, signal, relay), their Docker images, port mappings, volumes, and startup order. Modify this to change resource limits, add services, or adjust networking. | -| `management.json` | Central configuration for the management server including STUN/relay server addresses, authentication settings, and database configuration. Changes here affect how peers connect and authenticate. | -| `relay.env` | Environment variables for the relay service including the authentication secret, public address, and embedded STUN server settings. The relay secret here must match `management.json`. | +| `docker-compose.yml` | Defines all services (dashboard, netbird-server, optionally traefik), their Docker images, port mappings, volumes, and startup order. Structure varies depending on the reverse proxy option chosen during setup. | +| `config.yaml` | Unified server configuration for the combined NetBird server: listen addresses, STUN, relay authentication, embedded IdP, and database settings. Replaces the old `management.json` and `relay.env` files. | | `dashboard.env` | Configures the web dashboard including API endpoints, OAuth2/OIDC settings, and optional SSL settings for standalone deployments without a reverse proxy. | -| `Caddyfile` | Configures the built-in Caddy reverse proxy for SSL termination and routing requests to NetBird services. Only present when using the default `getting-started.sh` deployment with Caddy. | ### File Locations @@ -28,10 +26,11 @@ After running the installation script, configuration files are located in the di ``` ./ ├── docker-compose.yml -├── management.json -├── relay.env +├── config.yaml ├── dashboard.env -└── Caddyfile # Only when using built-in Caddy +└── nginx-netbird.conf # Only when using Nginx reverse proxy + npm-advanced-config.txt # Only when using Nginx Proxy Manager + caddyfile-netbird.txt # Only when using Caddy reverse proxy ``` --- @@ -44,39 +43,59 @@ The Docker Compose file defines all NetBird services, their dependencies, networ | Service | Image | Internal Port | External (Exposed) | Description | |---------|-------|---------------|-------------------|-------------| +| `traefik` | `traefik:v3.6` | 80, 443 | 80:80, 443:443 | Handles TLS termination via Let's Encrypt and routes incoming HTTPS requests to the appropriate NetBird services. Only included when using the built-in Traefik option (option 0). | | `dashboard` | `netbirdio/dashboard` | 80 | 8080:80 | The web-based management console where administrators configure networks, manage peers, create access policies, and view activity logs. Includes an embedded nginx server for serving the UI. | -| `management` | `netbirdio/management` | 80 | 8081:80 | The central control plane that handles peer registration, distributes network configurations, manages access policies, and hosts the embedded identity provider. All peers connect to this service on startup. | -| `signal` | `netbirdio/signal` | 80 | 8083:80 | Rendezvous service that facilitates peer connections by enabling peers to exchange connection offers and establish direct WireGuard tunnels. Handles only connection setup metadata, not actual traffic. Uses HTTP/2 protocol via the reverse proxy. | -| `relay` | `netbirdio/relay` | 80, 3478/udp | 8084:80, 3478:3478/udp | Routes encrypted traffic between peers when direct connections fail due to restrictive NATs or firewalls. Also provides embedded STUN on UDP 3478 for NAT type detection. | -| `caddy` | `caddy` | 80, 443 | 80:80, 443:443 | Handles TLS termination and routes incoming HTTPS requests to the appropriate NetBird services. Only included in default `getting-started.sh` deployments; can be replaced with your own reverse proxy. | +| `netbird-server` | `netbirdio/netbird-server` | 80, 3478/udp | 8081:80, 3478:3478/udp | Combined server that includes management, signal, relay, and embedded STUN in a single container. Configured via `config.yaml`. | -**Internal vs External ports**: Internal ports are what services listen on inside their containers. External (Exposed) ports show the host-to-container mapping used when running without the built-in Caddy (e.g., with Nginx, Traefik, or other reverse proxies). When using the default Caddy deployment, only Caddy exposes ports externally. +**Internal vs External ports**: Internal ports are what services listen on inside their containers. External (Exposed) ports show the host-to-container mapping used when running without the built-in Traefik (e.g., with Nginx or other reverse proxies). When using the default Traefik deployment, only Traefik exposes ports externally. -The relay service includes an embedded STUN server, eliminating the need for a separate coturn container. STUN functionality is enabled via the `NB_ENABLE_STUN` environment variable in `relay.env`. +The `netbird-server` container combines what were previously separate management, signal, relay, and STUN containers into a single service. This simplifies the deployment architecture while maintaining the same functionality. -### Default Settings +### Traefik Service -The compose file includes these defaults applied to all services: +The Traefik service is only present when using the built-in reverse proxy option (option 0 during setup). It handles automatic TLS certificate provisioning via Let's Encrypt and routes requests to the correct backend services. ```yaml -x-default: &default - restart: 'unless-stopped' +traefik: + image: traefik:v3.6 + container_name: netbird-traefik + restart: unless-stopped + networks: [netbird] + command: + - "--providers.docker=true" + - "--providers.docker.exposedbydefault=false" + - "--providers.docker.network=netbird" + - "--entrypoints.web.address=:80" + - "--entrypoints.websecure.address=:443" + - "--entrypoints.websecure.transport.respondingTimeouts.readTimeout=0" + - "--entrypoints.web.http.redirections.entrypoint.to=websecure" + - "--entrypoints.web.http.redirections.entrypoint.scheme=https" + - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true" + - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json" + ports: + - '443:443' + - '80:80' + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - netbird_traefik_letsencrypt:/letsencrypt logging: - driver: 'json-file' + driver: "json-file" options: - max-size: '500m' - max-file: '2' + max-size: "500m" + max-file: "2" ``` + +The `readTimeout=0` setting on the websecure entrypoint disables read timeouts, which is required for long-lived gRPC and WebSocket connections used by the signal and relay services. + + ### Dashboard Service -The dashboard provides the web interface for NetBird management. - -**With built-in Caddy (default):** +**With built-in Traefik (default):** ```yaml dashboard: image: netbirdio/dashboard:latest @@ -85,24 +104,14 @@ dashboard: networks: [netbird] env_file: - ./dashboard.env - logging: - driver: "json-file" - options: - max-size: "500m" - max-file: "2" -``` - -**With external reverse proxy (exposed ports):** -```yaml -dashboard: - image: netbirdio/dashboard:latest - container_name: netbird-dashboard - restart: unless-stopped - networks: [netbird] - ports: - - '127.0.0.1:8080:80' - env_file: - - ./dashboard.env + labels: + - traefik.enable=true + - traefik.http.routers.netbird-dashboard.rule=Host(`netbird.example.com`) + - traefik.http.routers.netbird-dashboard.entrypoints=websecure + - traefik.http.routers.netbird-dashboard.tls=true + - traefik.http.routers.netbird-dashboard.tls.certresolver=letsencrypt + - traefik.http.routers.netbird-dashboard.priority=1 + - traefik.http.services.netbird-dashboard.loadbalancer.server.port=80 logging: driver: "json-file" options: @@ -111,32 +120,44 @@ dashboard: ``` -The dashboard service is configured via the `dashboard.env` file. See the [dashboard.env section](#dashboard-env) for the full list of environment variables. When using the built-in Caddy, no ports are exposed directly from the dashboard container; Caddy routes traffic to it internally. +The dashboard service is configured via the `dashboard.env` file. See the [dashboard.env section](#dashboardenv) for the full list of environment variables. When using the built-in Traefik, no ports are exposed directly from the dashboard container; Traefik routes traffic to it internally via Docker labels. -### Management Service +### NetBird Server Service -The management service is the core of NetBird, handling peer registration, authentication, and network coordination. +The combined server runs management, signal, relay, and STUN in a single container, configured by `config.yaml`. -**With built-in Caddy (default):** +**With built-in Traefik (default):** ```yaml -management: - image: netbirdio/management:latest - container_name: netbird-management +netbird-server: + image: netbirdio/netbird-server:latest + container_name: netbird-server restart: unless-stopped networks: [netbird] + ports: + - '3478:3478/udp' volumes: - - netbird_management:/var/lib/netbird - - ./management.json:/etc/netbird/management.json - command: [ - "--port", "80", - "--log-file", "console", - "--log-level", "info", - "--disable-anonymous-metrics=false", - "--single-account-mode-domain=netbird.selfhosted", - "--dns-domain=netbird.selfhosted", - "--idp-sign-key-refresh-enabled", - ] + - netbird_data:/var/lib/netbird + - ./config.yaml:/etc/netbird/config.yaml + command: ["--config", "/etc/netbird/config.yaml"] + 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.entrypoints=websecure + - traefik.http.routers.netbird-grpc.tls=true + - traefik.http.routers.netbird-grpc.tls.certresolver=letsencrypt + - traefik.http.routers.netbird-grpc.service=netbird-server-h2c + # Backend router (relay, WebSocket, API, OAuth2) + - traefik.http.routers.netbird-backend.rule=Host(`netbird.example.com`) && (PathPrefix(`/relay`) || PathPrefix(`/ws-proxy/`) || PathPrefix(`/api`) || PathPrefix(`/oauth2`)) + - traefik.http.routers.netbird-backend.entrypoints=websecure + - traefik.http.routers.netbird-backend.tls=true + - traefik.http.routers.netbird-backend.tls.certresolver=letsencrypt + - traefik.http.routers.netbird-backend.service=netbird-server + # Services + - traefik.http.services.netbird-server.loadbalancer.server.port=80 + - traefik.http.services.netbird-server-h2c.loadbalancer.server.port=80 + - traefik.http.services.netbird-server-h2c.loadbalancer.server.scheme=h2c logging: driver: "json-file" options: @@ -146,25 +167,18 @@ management: **With external reverse proxy (exposed ports):** ```yaml -management: - image: netbirdio/management:latest - container_name: netbird-management +netbird-server: + image: netbirdio/netbird-server:latest + container_name: netbird-server restart: unless-stopped networks: [netbird] ports: - '127.0.0.1:8081:80' + - '3478:3478/udp' volumes: - - netbird_management:/var/lib/netbird - - ./management.json:/etc/netbird/management.json - command: [ - "--port", "80", - "--log-file", "console", - "--log-level", "info", - "--disable-anonymous-metrics=false", - "--single-account-mode-domain=netbird.selfhosted", - "--dns-domain=netbird.selfhosted", - "--idp-sign-key-refresh-enabled", - ] + - netbird_data:/var/lib/netbird + - ./config.yaml:/etc/netbird/config.yaml + command: ["--config", "/etc/netbird/config.yaml"] logging: driver: "json-file" options: @@ -172,491 +186,170 @@ management: max-file: "2" ``` -To use an external database, add environment variables: -```yaml - environment: - - NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://user:password@host:5432/netbird - # Or for MySQL: - # - NETBIRD_STORE_ENGINE_MYSQL_DSN=user:password@tcp(host:3306)/netbird -``` +#### Traefik Routing Labels -#### Command-Line Flags +When using the built-in Traefik, the `netbird-server` service uses two routers to handle different traffic types: -| Flag | Default | Description | -|------|---------|-------------| -| `--port` | `80` | The port the management server listens on inside the container. The default deployment uses port 80 internally; TLS is handled by the reverse proxy. | -| `--log-file` | `console` | Where to write log output. Use `console` for Docker logging (recommended) or specify a file path. Logs to console are captured by Docker's logging driver. | -| `--log-level` | `info` | Controls log verbosity. Use `debug` for troubleshooting connection issues, `info` for normal operation, `warn` or `error` for quieter logs in production. | -| `--disable-anonymous-metrics` | `false` | When `true`, stops sending anonymous usage statistics to NetBird. Set to `true` for air-gapped environments or if your security policy prohibits telemetry. | -| `--single-account-mode-domain` | `netbird.selfhosted` | Restricts all users to a single NetBird account associated with this domain. Required for most self-hosted deployments to prevent users from creating separate accounts. | -| `--dns-domain` | `netbird.selfhosted` | The DNS suffix used for peer name resolution within NetBird (e.g., `peer-name.netbird.selfhosted`). Must not conflict with your existing DNS domains. | -| `--idp-sign-key-refresh-enabled` | `false` | Enables automatic refresh of IdP signing keys. Recommended for the embedded IdP to ensure tokens remain valid. | +| Router | Path Prefixes | Backend Service | Purpose | +|--------|---------------|-----------------|---------| +| `netbird-grpc` | `/signalexchange.SignalExchange/`, `/management.ManagementService/` | `netbird-server-h2c` (h2c scheme) | gRPC traffic for signal exchange and management API. Uses HTTP/2 cleartext (h2c) backend because gRPC requires HTTP/2. | +| `netbird-backend` | `/relay`, `/ws-proxy/`, `/api`, `/oauth2` | `netbird-server` (http scheme) | HTTP traffic for relay connections, WebSocket proxying, REST API, and OAuth2/OIDC endpoints. | -### Signal Service - -The signal service acts as a rendezvous service for facilitating peer-to-peer connections. It enables peers to discover each other and exchange connection information needed to establish direct WireGuard tunnels. - -**With built-in Caddy (default):** -```yaml -signal: - image: netbirdio/signal:latest - container_name: netbird-signal - restart: unless-stopped - networks: [netbird] - logging: - driver: "json-file" - options: - max-size: "500m" - max-file: "2" -``` - -**With external reverse proxy (exposed ports):** -```yaml -signal: - image: netbirdio/signal:latest - container_name: netbird-signal - restart: unless-stopped - networks: [netbird] - ports: - - '127.0.0.1:8083:80' - logging: - driver: "json-file" - options: - max-size: "500m" - max-file: "2" -``` +The dashboard router has `priority=1` (lowest), so it acts as a catch-all for requests that don't match the more specific server routes. -The signal service listens on port 80 internally and uses HTTP/2 protocol. The reverse proxy (Caddy or your own) handles TLS termination and routes signal traffic to this service. +The STUN port (3478/udp) must always be exposed publicly, regardless of reverse proxy configuration. STUN uses UDP for NAT detection and cannot be proxied through HTTP reverse proxies. The STUN server is embedded in the combined `netbird-server` container and configured via the `server.stunPorts` field in `config.yaml`. -### Relay Service - -The relay service is a public service that forwards packets when direct peer-to-peer connections are not possible. It also includes an embedded STUN server for NAT detection and traversal. - -**With built-in Caddy (default):** -```yaml -relay: - image: netbirdio/relay:latest - container_name: netbird-relay - restart: unless-stopped - networks: [netbird] - ports: - - '3478:3478/udp' # Embedded STUN server (must be exposed publicly) - env_file: - - ./relay.env - logging: - driver: "json-file" - options: - max-size: "500m" - max-file: "2" -``` - -**With external reverse proxy (exposed ports):** -```yaml -relay: - image: netbirdio/relay:latest - container_name: netbird-relay - restart: unless-stopped - networks: [netbird] - ports: - - '127.0.0.1:8084:80' # Relay WebSocket (for reverse proxy) - - '3478:3478/udp' # Embedded STUN server (must be exposed publicly) - env_file: - - ./relay.env - logging: - driver: "json-file" - options: - max-size: "500m" - max-file: "2" -``` - - -The STUN port (3478/udp) must always be exposed publicly, regardless of reverse proxy configuration. STUN uses UDP for NAT detection and cannot be proxied through HTTP reverse proxies. - - -The relay service is configured via the `relay.env` file. See the [relay.env section](#relay-env) for detailed configuration options. - - - - Log verbosity level. Options: `debug`, `info`, `warn`, `error`. Default: `info` - - - Address and port to listen on. Format: `:port`. Default: `:80` - - - Public address for peers to connect. Format: `rel://hostname:port` or `rels://hostname:port` for TLS. - - - Shared secret for relay authentication. Must match `management.json` Relay.Secret. - - - Enable the embedded STUN server. Default: `false` - - - Comma-separated list of UDP ports for the STUN server. Default: `3478` - - - -### STUN Server (Embedded in Relay) - - -Starting with the current quickstart installation, STUN functionality is **embedded directly in the relay service**. The separate coturn container is no longer used in the default deployment. This simplifies the architecture and reduces the number of containers to manage. - - -The embedded STUN server is enabled by setting `NB_ENABLE_STUN=true` in `relay.env`. The STUN server listens on UDP port 3478 by default. - -#### Legacy Coturn Configuration - -If you have an existing installation using coturn, or need advanced TURN functionality (such as time-based credentials or TCP relay), you can still use a separate coturn container. See the [advanced self-hosting guide](/selfhosted/selfhosted-guide) for coturn configuration details. - ### Volume Configuration | Volume | Mount Point | Purpose | |--------|-------------|---------| -| `netbird_management` | `/var/lib/netbird` | Stores the management database (SQLite by default), encryption keys, and persistent state. Back up this volume regularly to preserve your accounts, peers, policies, and setup keys. | -| `netbird_caddy_data` | `/data` | Stores Caddy's TLS certificates and other persistent data. Only used when deploying with the built-in Caddy reverse proxy. Preserve this volume to maintain TLS certificates across restarts. | - - -The `getting-started.sh` deployment uses only two volumes: `netbird_management` for the management database and `netbird_caddy_data` for Caddy's certificate storage. The signal and relay services do not require persistent volumes in the default configuration. - +| `netbird_data` | `/var/lib/netbird` | Stores the management database (SQLite by default), encryption keys, and persistent state. Back up this volume regularly to preserve your accounts, peers, policies, and setup keys. | +| `netbird_traefik_letsencrypt` | `/letsencrypt` | Stores Traefik's Let's Encrypt TLS certificates. Only used when deploying with the built-in Traefik reverse proxy (option 0). Preserve this volume to maintain TLS certificates across restarts. | --- -## management.json +## config.yaml -The management configuration file controls the core behavior of the NetBird Management service. This is the most complex configuration file. - -### Authentication - -NetBird comes with built-in local user management and also supports integration with any OIDC-compatible identity provider. -This enables Single Sign-On (SSO), Multi-Factor Authentication (MFA), and centralized user management. -For setup instructions, see the [Authentication & IdPs page](/selfhosted/identity-providers) for configuration details. - -### Configuration Sections - -The `management.json` file for `getting-started.sh` deployments uses these sections: - -| Section | Required | Description | -|---------|----------|-------------| -| `Stuns` | Yes | Lists STUN servers that peers use to discover their public IP address and NAT type. Without working STUN, peers cannot establish direct connections and will always use the relay. | -| `Relay` | Yes | Configures relay server addresses and authentication. Peers use relay servers when direct connections fail. The secret here must match `NB_AUTH_SECRET` in `relay.env`. | -| `Signal` | Yes | Specifies how the management server connects to the signal service. Peers receive this address and use it to exchange connection offers with other peers. | -| `EmbeddedIdP` | Yes | Enables and configures the built-in identity provider (based on DEX). Handles user authentication, token issuance, and OIDC endpoints. Required for `getting-started.sh` deployments. | +The unified configuration file controls the combined NetBird server. It replaces the separate `management.json` and `relay.env` files from older deployments. ### Complete Structure -```json -{ - "Stuns": [...], - "Relay": {...}, - "Signal": {...}, - "Datadir": "/var/lib/netbird", - "DataStoreEncryptionKey": "...", - "EmbeddedIdP": { - "Enabled": true, - "Issuer": "https://your-domain/oauth2", - "DashboardRedirectURIs": [...] - } -} +```yaml +server: + listenAddress: ":80" + exposedAddress: "https://netbird.example.com:443" + stunPorts: + - 3478 + metricsPort: 9090 + healthcheckAddress: ":9000" + logLevel: "info" + logFile: "console" + + authSecret: "your-relay-auth-secret" + dataDir: "/var/lib/netbird" + + auth: + issuer: "https://netbird.example.com/oauth2" + signKeyRefreshEnabled: true + dashboardRedirectURIs: + - "https://netbird.example.com/nb-auth" + - "https://netbird.example.com/nb-silent-auth" + cliRedirectURIs: + - "http://localhost:53000/" + + store: + engine: "sqlite" # sqlite, postgres, or mysql + dsn: "" # Connection string for postgres or mysql + encryptionKey: "your-encryption-key" ``` -### Stuns Section - -Configures STUN servers used for NAT detection and traversal. - -**What does STUN do?** - -STUN (Session Traversal Utilities for NAT) helps NetBird peers discover their public IP address and the type of NAT they are behind. This information is essential for establishing direct peer-to-peer connections: - -- **NAT type detection** - Determines if peers can connect directly or need relay assistance -- **Public address discovery** - Peers learn their external IP and port, which they share via the signal server -- **Connection optimization** - Enables direct connections when possible, reducing latency and relay load - -The embedded STUN server in the relay service (enabled via `NB_ENABLE_STUN=true` in `relay.env`) is typically sufficient for most deployments. - -```json -"Stuns": [ - { - "Proto": "udp", - "URI": "stun:netbird.example.com:3478", - "Username": "", - "Password": null - } -] -``` +### Server Settings - - Protocol for STUN communication. Options: `udp`, `tcp`. Default: `udp` + + The address and port the combined server listens on inside the container. Default: `:80`. TLS is handled by the reverse proxy. - - STUN server URI. Format: `stun:hostname:port` + + The public-facing URL where peers connect to the server. Format: `https://hostname:port`. This address is distributed to peers and must be reachable from all clients. - - Optional username for authenticated STUN. Usually empty. + + List of UDP ports for the embedded STUN server. Default: `[3478]`. These ports must be exposed in `docker-compose.yml` and reachable through firewalls. - - Optional password for authenticated STUN. Usually `null`. + + Port to expose Prometheus metrics endpoint. Default: `9090`. Metrics are available at `/metrics` for monitoring. + + + Address for health check endpoint. Default: `:9000`. Exposes `/health` for container orchestration and load balancer health probes. + + + Controls log verbosity. Options: `debug`, `info`, `warn`, `error`. Default: `info`. Use `debug` for troubleshooting connection issues. + + + Where to write log output. Use `console` for Docker logging (recommended) or specify a file path. Default: `console`. + + + Shared secret for relay authentication. Auto-generated by the setup script. This secret is used internally by the combined server for relay credential validation. + + + Data directory path where the server stores its database and state files. Default: `/var/lib/netbird`. Maps to the `netbird_data` Docker volume. -### Relay Section +### Authentication Settings -Configures the NetBird relay server connection for NAT traversal. +Configures the built-in identity provider (embedded IdP) that handles user authentication and management. -**What does the relay service do?** + + + The issuer URL for OAuth2/OIDC tokens. Format: `https://your-domain/oauth2`. This URL is used to validate JWT tokens and must be accessible to clients. + + + Enables automatic refresh of IdP signing keys. Recommended: `true`. Ensures tokens remain valid by periodically rotating signing keys. + + + Allowed redirect URIs for OAuth2 authorization flow. Must include the dashboard authentication callbacks, typically `/nb-auth` and `/nb-silent-auth` on your domain. + + + Redirect URIs for CLI-based authentication. Default: `["http://localhost:53000/"]`. Used when authenticating via the `netbird` CLI tool. + + -When two NetBird peers cannot establish a direct WireGuard connection (due to restrictive NATs, firewalls, or network topology), traffic is routed through the relay server. The relay acts as an encrypted intermediary, ensuring connectivity even in challenging network environments. +When the embedded IdP is active, the server automatically hosts these OIDC endpoints: -- **Automatic fallback** - Peers attempt direct connections first; relay is used only when needed -- **End-to-end encryption** - Traffic remains WireGuard-encrypted; the relay cannot read packet contents -- **Credential-based authentication** - The shared secret ensures only authorized peers can use your relay - -```json -"Relay": { - "Addresses": ["rels://netbird.example.com:443"], - "CredentialsTTL": "24h", - "Secret": "your-relay-secret" -} -``` +- **Discovery**: `https://your-domain/oauth2/.well-known/openid-configuration` +- **JWKS (signing keys)**: `https://your-domain/oauth2/keys` +- **Token issuance**: `https://your-domain/oauth2/token` +- **Device authorization**: `https://your-domain/oauth2/device/authorize` -The relay address uses the same port as HTTPS (443) when using TLS (`rels://`), or port 80 when not using TLS (`rel://`). The reverse proxy routes `/relay*` paths to the relay service internally. +NetBird also supports integration with external OIDC-compatible identity providers for Single Sign-On (SSO), Multi-Factor Authentication (MFA), and centralized user management. See the [Authentication & IdPs page](/selfhosted/identity-providers) for configuration details. +### Store Settings + +Configures the database backend for storing all NetBird management data including accounts, peers, groups, access policies, routes, DNS configuration, setup keys, and activity logs. + - - Array of relay server addresses. Format: `rels://hostname:port` for TLS or `rel://hostname:port` for unencrypted. Default uses the public HTTPS port (443). + + Database engine. Options: `sqlite`, `postgres`, `mysql`. Default: `sqlite`. - - Time-to-live for relay credentials. Default: `24h` + + Connection string for postgres or mysql engines. For postgres: `host=localhost user=netbird password=secret dbname=netbird port=5432`. Alternatively, use the `NETBIRD_STORE_ENGINE_POSTGRES_DSN` or `NETBIRD_STORE_ENGINE_MYSQL_DSN` environment variables. - - Shared authentication secret. Must match relay server's `NB_AUTH_SECRET`. + + 32-byte (256-bit) encryption key for sensitive data at rest. Used to encrypt setup keys, API tokens, and other secrets stored in the database. Auto-generated by the setup script. - -The relay secret must be identical in both `management.json` and the relay service environment. A mismatch will cause relay connections to fail. - - -### Signal Section - -Configures the connection to the Signal service for peer-to-peer connection establishment. - -**What does the signal service do?** - -The signal service acts as a rendezvous service that facilitates peer connections. When two peers want to establish a direct connection, they exchange connection offers, answers, and network candidates through the signal server. This coordination enables peers to discover each other and negotiate the optimal connection path. - -- **Rendezvous service** - Enables peers to find each other and exchange the information needed to establish direct WireGuard tunnels -- **No traffic routing** - Unlike the relay, the signal server only handles connection setup metadata, not actual traffic -- **Persistent connections** - Peers maintain a connection to the signal server to receive incoming connection requests -- **HTTP/2 protocol** - Clients connect via the reverse proxy on port 443 (HTTPS) or 80 (HTTP) - -```json -"Signal": { - "Proto": "https", - "URI": "netbird.example.com:443", - "Username": "", - "Password": null -} -``` - - -The signal URI uses the same public HTTPS port (443) as other services. The reverse proxy routes signal traffic (`/signalexchange.SignalExchange/*` and `/ws-proxy/signal*`) to the signal service internally. - - - - - Protocol for signal communication. Options: `http`, `https`. Use `https` for production deployments with TLS, or `http` for non-TLS setups. - - - Signal server address. Format: `hostname:port`. Uses the public port (443 for HTTPS, 80 for HTTP). - - - Optional authentication username. Usually empty. - - - Optional authentication password. Usually `null`. - - - -### ReverseProxy Section - -Configures trusted reverse proxies for proper client IP detection. - -```json -"ReverseProxy": { - "TrustedHTTPProxies": [], - "TrustedHTTPProxiesCount": 0, - "TrustedPeers": ["0.0.0.0/0"] -} -``` - - - - List of trusted proxy IP addresses or CIDR ranges. - - - Number of trusted proxy hops. Used with X-Forwarded-For header parsing. - - - CIDR ranges of trusted peers. Default: `["0.0.0.0/0"]` (trust all). - - - - -When running behind a reverse proxy, configure `TrustedHTTPProxies` with your proxy's IP to ensure accurate client IP logging and rate limiting. - - -### StoreConfig Section - -Configures the database backend for storing all NetBird management data. - -**What data is stored in the database?** - -The management database contains all persistent state for your NetBird deployment: +**What data is stored?** - **Accounts and users** - User accounts, roles, and permissions - **Peers** - Registered devices, their WireGuard keys, IP assignments, and metadata -- **Groups** - Peer groupings used for access control and network organization -- **Access policies** - Network access rules defining which peers can communicate -- **Routes** - Network routes for accessing external subnets through NetBird peers -- **DNS configuration** - Custom DNS settings and nameserver groups -- **Setup keys** - Keys used for automated peer enrollment -- **Activity logs** - Audit trail of user and system actions -- **Posture checks** - Device security compliance policies +- **Groups** - Peer groupings used for access control +- **Access policies** - Network access rules +- **Routes** - Network routes for external subnets +- **DNS configuration** - Custom DNS settings +- **Setup keys** - Keys for automated peer enrollment +- **Activity logs** - Audit trail -**Where is the data stored?** +| Engine | Storage | Notes | +|--------|---------|-------| +| SQLite (default) | `/var/lib/netbird/` volume | File-based database stored in the `netbird_data` Docker volume. Zero configuration required, but does not support concurrent writes or running multiple management instances. Best for testing or small deployments. | +| PostgreSQL | External database server | Recommended for production deployments. Supports concurrent access, enabling multiple management instances for high availability. | +| MySQL | External database server | Alternative to PostgreSQL for organizations that have standardized on MySQL/MariaDB. Provides similar benefits including concurrent access. | -| Engine | Storage Location | Notes | -|--------|------------------|-------| -| SQLite (default) | `/var/lib/netbird/` volume | File-based database stored in the `netbird-mgmt` Docker volume. Zero configuration required, but does not support concurrent writes or running multiple management instances. Best for testing or small deployments with fewer than 100 peers. | -| PostgreSQL | External database server | Recommended for production deployments. Supports concurrent access, enabling multiple management instances for high availability. Requires managing a separate PostgreSQL server but offers standard backup tools and replication options. | -| MySQL | External database server | Alternative to PostgreSQL for organizations that have standardized on MySQL/MariaDB. Provides similar benefits to PostgreSQL including concurrent access and standard backup procedures. | +For PostgreSQL or MySQL, set the connection string via the `server.store.dsn` field in `config.yaml` or environment variables on the `netbird-server` container. See [Using an External Database](#using-an-external-database) below. -```json -"StoreConfig": { - "Engine": "sqlite" -} -``` - - - - Database engine. Options: `sqlite`, `postgres`, `mysql`. Default: `sqlite` - - - -For PostgreSQL or MySQL, set the connection string via environment variables: -- `NETBIRD_STORE_ENGINE_POSTGRES_DSN` for PostgreSQL -- `NETBIRD_STORE_ENGINE_MYSQL_DSN` for MySQL - - -For production deployments with multiple users or high availability requirements, consider using PostgreSQL. SQLite is convenient for testing and small deployments but does not support concurrent writes or easy backups while the service is running. - - -See [Management Postgres Store](/selfhosted/postgres-store) for PostgreSQL setup. - -### EmbeddedIdP Section - -Configures the built-in identity provider that handles user authentication and management. The embedded IdP is based on DEX and supports both local user management and connections to external identity providers configured through the Dashboard. - -```json -"EmbeddedIdP": { - "Enabled": true, - "Issuer": "https://netbird.example.com/oauth2", - "DashboardRedirectURIs": [ - "https://netbird.example.com/nb-auth", - "https://netbird.example.com/nb-silent-auth" - ] -} -``` - - - - Enable the embedded identity provider. When `true`, the management server hosts OAuth2/OIDC endpoints at `/oauth2/`. - - - The issuer URL for tokens. Should be `https://your-domain/oauth2`. This URL is used to validate JWT tokens and must be accessible to clients. - - - Allowed redirect URIs for OAuth2 authorization flow. Must include the dashboard authentication callbacks, typically `/nb-auth` and `/nb-silent-auth` on your domain. - - - -When `EmbeddedIdP.Enabled` is `true`, the management server automatically: -- Hosts OIDC discovery at `https://your-domain/oauth2/.well-known/openid-configuration` -- Provides JWKS (signing keys) at `https://your-domain/oauth2/keys` -- Handles token issuance at `https://your-domain/oauth2/token` -- Manages device authorization at `https://your-domain/oauth2/device/authorize` -- Provides user management through the Dashboard UI - -### Other Top-Level Settings - - - - Disable the default "allow all" access policy for new accounts. When `true`, new accounts start with no access rules, requiring explicit policy creation before peers can communicate. Default: `false` - - - Data directory path where the management service stores its database and state files. Usually set via command line (`--datadir`). Default: `/var/lib/netbird` - - - 32-byte (256-bit) encryption key for sensitive data at rest. Used to encrypt setup keys, API tokens, and other secrets stored in the database. Auto-generated by setup scripts. - - +See [Management Postgres Store](/selfhosted/postgres-store) for detailed PostgreSQL setup. -Keep `DataStoreEncryptionKey` secure and backed up. This key encrypts sensitive data in your database, including setup keys and API tokens. Losing this key means losing access to encrypted data, and you will need to regenerate all setup keys and API tokens. +Keep `server.store.encryptionKey` secure and backed up. This key encrypts sensitive data in your database, including setup keys and API tokens. Losing this key means losing access to encrypted data, and you will need to regenerate all setup keys and API tokens. --- -## relay.env - -Environment configuration for the relay service. This file is mounted into the relay container and configures both the relay and the embedded STUN server. - -```bash -# Log level: debug, info, warn, error -NB_LOG_LEVEL=info - -# Address to listen on for relay connections -NB_LISTEN_ADDRESS=:80 - -# Public address for peers to connect -# Use rel:// for unencrypted or rels:// for TLS -NB_EXPOSED_ADDRESS=rels://netbird.example.com:443 - -# Authentication secret (must match management.json Relay.Secret) -NB_AUTH_SECRET=your-secret-here - -# Embedded STUN server configuration -NB_ENABLE_STUN=true -NB_STUN_LOG_LEVEL=info -NB_STUN_PORTS=3478 -``` - -### All Relay Variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `NB_LOG_LEVEL` | `info` | Controls relay log verbosity. Use `debug` when troubleshooting connection issues to see detailed peer connection attempts and failures. | -| `NB_LISTEN_ADDRESS` | `:80` | The address and port the relay listens on inside the container. Format: `:port` or `address:port`. Usually left as `:80` since the container port is mapped externally. | -| `NB_EXPOSED_ADDRESS` | - | The public address peers use to connect to this relay. Use `rel://` for unencrypted or `rels://` for TLS. Must be reachable from all peers. | -| `NB_AUTH_SECRET` | - | Shared secret used to authenticate peers connecting to the relay. Must exactly match the `Relay.Secret` value in `management.json` or relay connections will fail. | -| `NB_ENABLE_STUN` | `false` | When `true`, the relay also runs an embedded STUN server. This eliminates the need for a separate coturn container for NAT detection. | -| `NB_STUN_PORTS` | `3478` | UDP port(s) for the embedded STUN server. Comma-separated for multiple ports. Must be exposed in `docker-compose.yml` and reachable through firewalls. | -| `NB_STUN_LOG_LEVEL` | `info` | Separate log level for the embedded STUN server. Use `debug` to troubleshoot NAT detection issues without increasing relay log verbosity. | -| `NB_METRICS_PORT` | - | Port to expose Prometheus metrics endpoint. When set, the relay exposes metrics at `/metrics` for monitoring connection counts and performance. | -| `NB_TLS_CERT_FILE` | - | Path to TLS certificate file for relay-terminated HTTPS. Only needed when the relay handles TLS directly instead of using a reverse proxy. | -| `NB_TLS_KEY_FILE` | - | Path to TLS private key file. Must be provided together with `NB_TLS_CERT_FILE` for direct TLS termination. | -| `NB_LETSENCRYPT_DATA_DIR` | - | Directory to store Let's Encrypt certificates when the relay obtains certificates automatically. Not needed when using an external reverse proxy for TLS. | -| `NB_LETSENCRYPT_DOMAINS` | - | Comma-separated domains for automatic Let's Encrypt certificate provisioning. The relay must be reachable on port 443 for ACME challenges. | -| `NB_LETSENCRYPT_EMAIL` | - | Email address for Let's Encrypt registration. Required for certificate expiry notifications if using automatic provisioning. | -| `NB_HEALTH_LISTEN_ADDRESS` | - | Address for health check endpoint (e.g., `:8080`). When set, exposes `/health` for container orchestration and load balancer health probes. | - ---- - ## dashboard.env Environment configuration for the dashboard service. @@ -665,20 +358,6 @@ Environment configuration for the dashboard service. The NetBird dashboard container includes an **embedded nginx server** that serves the dashboard web pages. This nginx instance is built into the container image and handles serving the static web UI files. -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Dashboard Container │ -│ ┌──────────────────────────────────────────────────────────┐ │ -│ │ Embedded Nginx │ │ -│ │ - Serves dashboard web UI │ │ -│ │ - Can handle SSL/TLS termination (standalone mode) │ │ -│ │ - Configurable via NGINX_* environment variables │ │ -│ └──────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -The `NGINX_SSL_PORT` and other `NGINX_*` environment variables control this embedded nginx server, not an external reverse proxy. - ```bash # Endpoints NETBIRD_MGMT_API_ENDPOINT=https://netbird.example.com @@ -694,13 +373,13 @@ AUTH_SUPPORTED_SCOPES=openid profile email groups AUTH_REDIRECT_URI=/nb-auth AUTH_SILENT_REDIRECT_URI=/nb-silent-auth -# SSL - disabled when behind reverse proxy (Caddy handles TLS) +# SSL - disabled when behind reverse proxy (Traefik handles TLS) NGINX_SSL_PORT=443 LETSENCRYPT_DOMAIN=none ``` -When using the built-in Caddy or an external reverse proxy, set `LETSENCRYPT_DOMAIN=none` because the reverse proxy handles TLS termination. Only set a domain here if running the dashboard standalone without a reverse proxy. +When using the built-in Traefik or an external reverse proxy, set `LETSENCRYPT_DOMAIN=none` because the reverse proxy handles TLS termination. Only set a domain here if running the dashboard standalone without a reverse proxy. ### Endpoint Configuration @@ -714,14 +393,14 @@ When using the built-in Caddy or an external reverse proxy, set `LETSENCRYPT_DOM | Variable | Description | |----------|-------------| -| `AUTH_AUDIENCE` | The expected audience claim in OAuth2 tokens. Must match the audience configured in your IdP. For embedded IdP, use `netbird-dashboard`. Incorrect values cause authentication failures. | +| `AUTH_AUDIENCE` | The expected audience claim in OAuth2 tokens. Must match the audience configured in your IdP. For embedded IdP, use `netbird-dashboard`. | | `AUTH_CLIENT_ID` | The OAuth2 client identifier for the dashboard application. For embedded IdP deployments, this is `netbird-dashboard`. Must match the client ID registered with your identity provider. | -| `AUTH_CLIENT_SECRET` | OAuth2 client secret for confidential clients. Leave empty for public clients (the default for browser-based apps like the dashboard). Only set this if your IdP requires a confidential client. | +| `AUTH_CLIENT_SECRET` | OAuth2 client secret for confidential clients. Leave empty for public clients (the default for browser-based apps like the dashboard). | | `AUTH_AUTHORITY` | The OAuth2/OIDC issuer URL (e.g., `https://netbird.example.com/oauth2` for embedded IdP). The dashboard fetches OIDC discovery metadata from `{AUTH_AUTHORITY}/.well-known/openid-configuration`. | -| `USE_AUTH0` | Set to `true` only when using Auth0 as your identity provider. Enables Auth0-specific authentication behavior. Leave as `false` for embedded IdP or other OIDC providers. | -| `AUTH_SUPPORTED_SCOPES` | Space-separated list of OAuth2 scopes to request during login. Standard value is `openid profile email groups`. The `groups` scope enables group-based access control if supported by your IdP. | -| `AUTH_REDIRECT_URI` | The path where the IdP redirects after authentication (e.g., `/nb-auth`). Must match a redirect URI registered with your identity provider. Incorrect values cause OAuth2 callback errors. | -| `AUTH_SILENT_REDIRECT_URI` | The path for silent token refresh (e.g., `/nb-silent-auth`). Used by the dashboard to refresh tokens in the background without user interaction. Must also be registered with your IdP. | +| `USE_AUTH0` | Set to `true` only when using Auth0 as your identity provider. Leave as `false` for embedded IdP or other OIDC providers. | +| `AUTH_SUPPORTED_SCOPES` | Space-separated list of OAuth2 scopes to request during login. Standard value is `openid profile email groups`. | +| `AUTH_REDIRECT_URI` | The path where the IdP redirects after authentication (e.g., `/nb-auth`). Must match a redirect URI registered with your identity provider. | +| `AUTH_SILENT_REDIRECT_URI` | The path for silent token refresh (e.g., `/nb-silent-auth`). Used by the dashboard to refresh tokens in the background without user interaction. | ### Embedded Nginx Configuration @@ -729,21 +408,12 @@ The dashboard container's embedded nginx server can be configured using these en | Variable | Default | Description | |----------|---------|-------------| -| `NGINX_SSL_PORT` | `443` | The HTTPS port for the dashboard's embedded nginx server. Only relevant in standalone mode without an external reverse proxy. When behind a reverse proxy, the dashboard serves HTTP internally. | -| `LETSENCRYPT_DOMAIN` | - | The domain name for automatic Let's Encrypt certificate provisioning. Set to `none` when using an external reverse proxy that handles TLS. The domain must resolve to this server for ACME challenges to succeed. | -| `LETSENCRYPT_EMAIL` | - | Email address for Let's Encrypt account registration and certificate expiry notifications. Required when `LETSENCRYPT_DOMAIN` is set. Let's Encrypt sends renewal reminders to this address. | +| `NGINX_SSL_PORT` | `443` | The HTTPS port for the dashboard's embedded nginx server. Only relevant in standalone mode without an external reverse proxy. | +| `LETSENCRYPT_DOMAIN` | - | The domain name for automatic Let's Encrypt certificate provisioning. Set to `none` when using an external reverse proxy that handles TLS. | +| `LETSENCRYPT_EMAIL` | - | Email address for Let's Encrypt account registration and certificate expiry notifications. Required when `LETSENCRYPT_DOMAIN` is set to an actual domain. | -**When do you need these nginx variables?** - -The `NGINX_SSL_PORT` and Let's Encrypt variables are **only necessary when running the dashboard standalone** without an external reverse proxy. In standalone mode, the dashboard's embedded nginx handles SSL/TLS termination directly. - -**For most installations** that use the built-in Caddy reverse proxy (the default `getting-started.sh` deployment) or an external reverse proxy like Traefik or Nginx, **you do not need to configure these nginx variables**. The reverse proxy handles SSL termination and routes traffic to the dashboard container, which serves content over HTTP internally. - -When behind a reverse proxy: -- Set `LETSENCRYPT_DOMAIN=none` to disable the dashboard's internal Let's Encrypt -- The embedded nginx will serve on HTTP (port 80) internally -- Your reverse proxy handles HTTPS and forwards requests to the dashboard +The `NGINX_SSL_PORT` and Let's Encrypt variables are **only necessary when running the dashboard standalone** without an external reverse proxy. For most installations using the built-in Traefik or an external reverse proxy, set `LETSENCRYPT_DOMAIN=none` and the embedded nginx will serve on HTTP (port 80) internally while your reverse proxy handles HTTPS. --- @@ -754,102 +424,101 @@ When behind a reverse proxy: To use PostgreSQL instead of SQLite: -1. Update `management.json`: -```json -"StoreConfig": { - "Engine": "postgres" -} +1. Update `config.yaml`: +```yaml +server: + store: + engine: "postgres" + dsn: "host=db-server user=netbird password=secret dbname=netbird port=5432" ``` -2. Set the connection string in `docker-compose.yml`: +Alternatively, you can use an environment variable instead of putting the DSN in the config file: ```yaml -management: +netbird-server: environment: - - NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://user:password@host:5432/netbird?sslmode=disable + - NETBIRD_STORE_ENGINE_POSTGRES_DSN=host=db-server user=netbird password=secret dbname=netbird port=5432 + # Or for MySQL: + # - NETBIRD_STORE_ENGINE_MYSQL_DSN=user:password@tcp(host:3306)/netbird ``` See [Management Postgres Store](/selfhosted/postgres-store) for detailed setup. -### Disabling Anonymous Metrics +### Changing Log Level -In `docker-compose.yml`, update the management command: +Update `server.logLevel` in `config.yaml`: ```yaml -management: - command: [ - "--port", "80", - "--disable-anonymous-metrics=true", - # ... other flags - ] +server: + logLevel: "debug" ``` -### Custom Relay Configuration +Options: `debug`, `info`, `warn`, `error`. Use `debug` for troubleshooting connection issues. -To use multiple relay servers, update `management.json`: +### Custom STUN Ports -```json -"Relay": { - "Addresses": [ - "rels://relay1.example.com:443", - "rels://relay2.example.com:443" - ], - "CredentialsTTL": "24h", - "Secret": "shared-secret" -} +To use multiple STUN ports, update `config.yaml`: + +```yaml +server: + stunPorts: + - 3478 + - 3479 ``` -Each relay server must use the same `NB_AUTH_SECRET`. Use `rels://` for TLS (port 443) or `rel://` for unencrypted (port 80). +Make sure to expose all ports in `docker-compose.yml`: +```yaml +netbird-server: + ports: + - '3478:3478/udp' + - '3479:3479/udp' +``` ### Behind a Reverse Proxy -When running behind your own reverse proxy (Traefik, Nginx, etc.): +When running behind your own reverse proxy (Nginx, Caddy, Nginx Proxy Manager, etc.) instead of the built-in Traefik: 1. Set `LETSENCRYPT_DOMAIN=none` in `dashboard.env` -2. Configure trusted proxies in `management.json`: -```json -"ReverseProxy": { - "TrustedHTTPProxies": ["10.0.0.1"], - "TrustedHTTPProxiesCount": 1, - "TrustedPeers": ["10.0.0.0/8"] -} -``` +2. Use the exposed-ports variant of `docker-compose.yml` (the setup script generates this automatically for options 1-4) +3. Configure your reverse proxy to route traffic to the correct containers and ports: + - Dashboard: `127.0.0.1:8080` (HTTP) + - NetBird Server: `127.0.0.1:8081` (HTTP), with gRPC paths using h2c (HTTP/2 cleartext) -See [Reverse Proxy Configuration](/selfhosted/reverse-proxy) for detailed templates. +See [Reverse Proxy Configuration](/selfhosted/reverse-proxy) for detailed templates for Nginx, Caddy, and other proxies. -### Configuring External TURN Servers +### Using External Services (Advanced) -The default NetBird deployment uses the relay service for NAT traversal, which handles most connectivity scenarios. External TURN servers are only needed for advanced use cases like geographically distributed deployments or environments with restrictive firewalls that block the relay protocol. +The default NetBird deployment includes embedded relay, signal, and STUN services. External services are only needed for advanced use cases. -To use external TURN servers (e.g., coturn deployed separately): +To use external STUN, relay, or signal servers, add overrides to `config.yaml`: -```json -"TURNConfig": { - "Turns": [ - { - "Proto": "udp", - "URI": "turn:turn-us.example.com:3478", - "Username": "netbird", - "Password": "password1" - }, - { - "Proto": "udp", - "URI": "turn:turn-eu.example.com:3478", - "Username": "netbird", - "Password": "password2" - } - ], - "CredentialsTTL": "12h", - "TimeBasedCredentials": false -} +```yaml +server: + # ... basic settings ... + + # Optional: Use external STUN servers + stuns: + - uri: "stun:stun.example.com:3478" + proto: "udp" + + # Optional: Use external relay servers + relays: + addresses: + - "rels://relay.example.com:443" + secret: "relay-auth-secret" + credentialsTTL: "24h" + + # Optional: Use external signal server + signalUri: "https://signal.example.com:443" ``` +See the [Scaling Your Self-Hosted Deployment](/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment) guide for more details on configuring external services. --- ## See Also - [Self-hosting Quickstart Guide](/selfhosted/selfhosted-quickstart) - Get started quickly with default settings -- [Reverse Proxy Configuration](/selfhosted/reverse-proxy) - Traefik, Nginx, Caddy setup +- [Reverse Proxy Configuration](/selfhosted/reverse-proxy) - Nginx, Caddy, NPM, HAProxy setup - [Management SQLite Store](/selfhosted/sqlite-store) - SQLite database details - [Management Postgres Store](/selfhosted/postgres-store) - PostgreSQL setup diff --git a/src/pages/selfhosted/identity-providers/index.mdx b/src/pages/selfhosted/identity-providers/index.mdx index 0f68adb3..e5771ced 100644 --- a/src/pages/selfhosted/identity-providers/index.mdx +++ b/src/pages/selfhosted/identity-providers/index.mdx @@ -81,6 +81,10 @@ NetBird supports any OIDC-compliant identity providers. Here are some popular pr your NetBird installation and will never be exposed to the public. + + If you plan to use the [Reverse Proxy](/manage/reverse-proxy) SSO feature with an external identity provider, you also need to register the reverse proxy callback URL with your IdP. See [Configure SSO for external identity providers](/selfhosted/migration/enable-reverse-proxy#configure-sso-for-external-identity-providers) for details. + +

Identity Providers List

diff --git a/src/pages/selfhosted/maintenance/backup.mdx b/src/pages/selfhosted/maintenance/backup.mdx index 537c9c1f..337deb0e 100644 --- a/src/pages/selfhosted/maintenance/backup.mdx +++ b/src/pages/selfhosted/maintenance/backup.mdx @@ -5,13 +5,28 @@ To back up your NetBird installation, you need to copy the configuration files a The configuration files are located in the folder where you ran [the installation script](/selfhosted/selfhosted-quickstart#installation-script). To back up, copy the files to a backup location: ```bash mkdir backup -cp docker-compose.yml Caddyfile dashboard.env management.json relay.env backup/ +cp docker-compose.yml dashboard.env config.yaml backup/ ``` For detailed information about each configuration file and its options, see the [Configuration Files Reference](/selfhosted/configuration-files). -To save the Management service databases, stop the Management service and copy the files from the store directory: +To save the server databases, stop the server and copy the files from the data directory: +```bash +docker compose stop netbird-server +docker compose cp -a netbird-server:/var/lib/netbird/ backup/ +docker compose start netbird-server +``` + +## Older Setup (Separate Containers) + +If your deployment uses the older setup with separate containers (`management`, `signal`, `relay`, `coturn`), back up the configuration files: +```bash +mkdir backup +cp docker-compose.yml Caddyfile dashboard.env management.json relay.env backup/ +``` + +To save the Management service database: ```bash docker compose stop management docker compose cp -a management:/var/lib/netbird/ backup/ diff --git a/src/pages/selfhosted/maintenance/remove.mdx b/src/pages/selfhosted/maintenance/remove.mdx index 66b1dacf..122fe66c 100644 --- a/src/pages/selfhosted/maintenance/remove.mdx +++ b/src/pages/selfhosted/maintenance/remove.mdx @@ -5,7 +5,7 @@ To remove the NetBird installation and all related data from your server, run th # remove all NetBird-related containers and volumes (data) docker compose down --volumes # remove downloaded and generated config files -rm -f docker-compose.yml Caddyfile dashboard.env management.json relay.env +rm -f docker-compose.yml dashboard.env config.yaml nginx-netbird.conf caddyfile-netbird.txt npm-advanced-config.txt ``` ## Get In Touch diff --git a/src/pages/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql.mdx b/src/pages/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql.mdx new file mode 100644 index 00000000..969995bc --- /dev/null +++ b/src/pages/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql.mdx @@ -0,0 +1,124 @@ +# Migrate from SQLite to PostgreSQL + +import {Note, Warning} from "@/components/mdx"; + +This guide is part of the [Splitting Your Self-Hosted Deployment](/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment) guide. It covers migrating your Management server database from SQLite to PostgreSQL. + +The default NetBird deployment uses SQLite, which stores all data in a single file. This works well for smaller setups, but you may want to migrate to PostgreSQL if: +- You want the database on a separate, dedicated machine +- You need better concurrency handling for larger deployments +- You prefer the operational tooling and backup options that PostgreSQL provides + +For smaller teams, SQLite is perfectly capable and migration is not required. + +## Set Up PostgreSQL + +If you don't already have a PostgreSQL instance, you can run one in Docker: + +```bash +docker run -d \ + --name postgres-server \ + -e POSTGRES_USER=postgres \ + -e POSTGRES_PASSWORD=password \ + -p 5432:5432 \ + -v postgres_data:/var/lib/postgresql/data \ + postgres:16 +``` + + +Replace the default `password` with a strong, unique password for production deployments. + + +## Back Up the SQLite Store + +Before migrating, create a backup of your SQLite database: + +```bash +mkdir backup +docker compose cp -a netbird-server:/var/lib/netbird/. backup/ +``` + +## Install pgloader + +The migration uses [pgloader](https://github.com/dimitri/pgloader) to transfer data from SQLite to PostgreSQL: + +```bash +# Debian/Ubuntu +sudo apt-get install pgloader + +# macOS +brew install pgloader +``` + +## Create the Migration File + +Create a file called `sqlite.load` with the following content: + +``` +LOAD DATABASE + FROM sqlite:///root/combined/backup/store.db + INTO postgresql://postgres:password@localhost:5432/postgres + +WITH include drop, create tables, create indexes, reset sequences + +CAST + column accounts.is_domain_primary_account to boolean, + column accounts.settings_peer_login_expiration_enabled to boolean, + column accounts.settings_peer_inactivity_expiration_enabled to boolean, + column accounts.settings_regular_users_view_blocked to boolean, + column accounts.settings_groups_propagation_enabled to boolean, + column accounts.settings_jwt_groups_enabled to boolean, + column accounts.settings_routing_peer_dns_resolution_enabled to boolean, + column accounts.settings_extra_peer_approval_enabled to boolean, + column accounts.settings_extra_user_approval_required to boolean, + column accounts.settings_lazy_connection_enabled to boolean +; +``` + + +Update the SQLite path and PostgreSQL connection string to match your environment. + + +## Run the Migration + +```bash +pgloader sqlite.load +``` + +## Update config.yaml + +On your main server, update the `store` section in `config.yaml` to use PostgreSQL: + +```yaml +server: + # ... existing settings ... + + store: + engine: "postgres" + dsn: "host=postgres-server user=postgres password=password dbname=postgres port=5432" +``` + +Alternatively, you can pass the connection string as an environment variable instead of putting it in the config file: + +```yaml + netbird-server: + environment: + - NETBIRD_STORE_ENGINE_POSTGRES_DSN=host=postgres-server user=postgres password=password dbname=postgres port=5432 +``` + +## Restart and Verify + +```bash +docker compose up -d +``` + +Check the logs to confirm PostgreSQL is being used: + +```bash +docker compose logs netbird-server | grep store +``` + +You should see: +``` +using Postgres store engine +``` \ No newline at end of file diff --git a/src/pages/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment.mdx b/src/pages/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment.mdx new file mode 100644 index 00000000..4d817cde --- /dev/null +++ b/src/pages/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment.mdx @@ -0,0 +1,96 @@ +# Splitting Your Self-Hosted Deployment + +import {Note, Warning} from "@/components/mdx"; + +This guide explains how to split your NetBird self-hosted deployment from a single-server setup into a distributed architecture for better reliability and performance. + +The most common approach is extracting the relay service (with its embedded STUN server) to separate servers and moving the PostgreSQL database to a dedicated machine. +In most cases, you won't need to extract the Signal server, but for completeness, this guide covers that as well. + +NetBird clients can tolerate a Management server outage as long as connections are already established through relays or peer-to-peer. +This makes a stable relay infrastructure especially important. + +This guide assumes you have already [deployed a single-server NetBird](/selfhosted/selfhosted-quickstart) and have a working configuration. + + + If you are looking for a high-availability setup for the Management and Signal services, this is available through an enterprise + commercial license [here](https://netbird.io/pricing#on-prem). + + +## Architecture Overview + +The default single-server deployment runs all services on one machine: **Traefik** (reverse proxy), **Dashboard** (web UI), +and a **combined netbird-server** container that includes Management, Signal, and Relay + STUN as components. Traefik handles TLS termination on ports 80/443, while STUN listens on UDP port 3478. The Management server uses a **SQLite** database by default. + +After splitting, the **main server** keeps Traefik, Dashboard, Management, and optionally Signal. +The **relay servers** run independently on different machines, each handling relay (port 443) and STUN (port 3478) traffic. Peers receive relay addresses from the Management server and connect to them directly. Optionally, the SQLite database can be migrated to **PostgreSQL** on a dedicated server, and Signal can also be extracted to its own machine. + +## Guides + +- [Set Up External Relay Servers](/selfhosted/maintenance/scaling/set-up-external-relays) — Deploy relay and STUN servers on separate machines and configure the main server to use them +- [Migrate from SQLite to PostgreSQL](/selfhosted/maintenance/scaling/migrate-sqlite-to-postgresql) — Move the Management database to a dedicated PostgreSQL instance (optional) +- [Set Up External Signal Server](/selfhosted/maintenance/scaling/set-up-external-signal) — Extract the Signal server to its own machine (optional) + +## Configuration Reference + +### Relay Server Environment Variables + +| Variable | Required | Description | +|----------|----------|-------------| +| `NB_LISTEN_ADDRESS` | Yes | Address to listen on (e.g., `:443`) | +| `NB_EXPOSED_ADDRESS` | Yes | Public relay URL (`rels://` for TLS, `rel://` for plain) | +| `NB_AUTH_SECRET` | Yes | Shared authentication secret | +| `NB_ENABLE_STUN` | No | Enable embedded STUN server (`true`/`false`) | +| `NB_STUN_PORTS` | No | STUN UDP port(s), default `3478` | +| `NB_LETSENCRYPT_DOMAINS` | No | Domain(s) for automatic Let's Encrypt certificates | +| `NB_LETSENCRYPT_EMAIL` | No | Email for Let's Encrypt notifications | +| `NB_TLS_CERT_FILE` | No | Path to TLS certificate (alternative to Let's Encrypt) | +| `NB_TLS_KEY_FILE` | No | Path to TLS private key | +| `NB_LOG_LEVEL` | No | Log level: `debug`, `info`, `warn`, `error` | + +### Main Server config.yaml - External Services + +```yaml +server: + # External STUN servers + stuns: + - uri: "stun:hostname:port" + proto: "udp" # or "tcp" + + # External relay servers + relays: + addresses: + - "rels://hostname:port" # TLS + - "rel://hostname:port" # Plain (not recommended) + secret: "shared-secret" + credentialsTTL: "24h" # How long relay credentials are valid + + # External signal server (optional, usually keep embedded) + # signalUri: "https://signal.example.com:443" +``` + +## Troubleshooting + +### Peers Can't Connect via Relay + +1. **Check secrets match**: The `authSecret`/`NB_AUTH_SECRET` must be identical everywhere +2. **Check firewall**: Ensure port 443/tcp is open on relay servers +3. **Check TLS**: If using `rels://`, ensure TLS is properly configured +4. **Check logs**: `docker compose logs relay` on the relay server + +### STUN Not Working + +1. **Check UDP port**: Ensure port 3478/udp is open and not blocked by firewall +2. **Check NAT**: Some carrier-grade NATs block STUN; try a different network +3. **Verify STUN is enabled**: `NB_ENABLE_STUN=true` on relay servers + +### Relay Shows as Unavailable + +1. **DNS resolution**: Ensure the relay domain resolves correctly +2. **Port reachability**: Test with `nc -zv relay-us.example.com 443` +3. **Certificate issues**: Check Let's Encrypt logs or certificate validity + +## See Also + +- [Configuration Files Reference](/selfhosted/configuration-files) - Full config.yaml documentation +- [Self-hosting Quickstart](/selfhosted/selfhosted-quickstart) - Initial deployment guide \ No newline at end of file diff --git a/src/pages/selfhosted/maintenance/scaling/set-up-external-relays.mdx b/src/pages/selfhosted/maintenance/scaling/set-up-external-relays.mdx new file mode 100644 index 00000000..7bb1e22f --- /dev/null +++ b/src/pages/selfhosted/maintenance/scaling/set-up-external-relays.mdx @@ -0,0 +1,280 @@ +# Set Up External Relay Servers + +import {Note, Warning} from "@/components/mdx"; + +This guide is part of the [Splitting Your Self-Hosted Deployment](/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment) guide. It covers deploying external relay and STUN servers and configuring your main server to use them. + +For each relay server you want to deploy: + +## Server Requirements + +- A Linux VM with at least **1 CPU** and **1GB RAM** +- Public IP address +- A domain name pointing to the server (e.g., `relay-us.example.com`) +- Docker installed +- Firewall ports open: **80/tcp** (Let's Encrypt HTTP challenge), **443/tcp** (relay), and **3478/udp** (STUN). If you configure multiple STUN ports, open all of them + +## Generate Authentication Secret + +All relay servers must share the same authentication secret with your main server. You can generate one with: + +```bash +# Generate a secure random secret +openssl rand -base64 32 +``` + +Save this secret - you'll need it for both the relay servers and your main server's config. + +## Create Relay Configuration + +On your relay server, create a directory and configuration: + +```bash +mkdir -p ~/netbird-relay +cd ~/netbird-relay +``` + +Create `relay.env` with your relay settings. The relay server can automatically obtain and renew TLS certificates via Let's Encrypt: + +```bash +NB_LOG_LEVEL=info +NB_LISTEN_ADDRESS=:443 +NB_EXPOSED_ADDRESS=rels://relay-us.example.com:443 +NB_AUTH_SECRET=your-shared-secret-here + +# TLS via Let's Encrypt (automatic certificate provisioning) +NB_LETSENCRYPT_DOMAINS=relay-us.example.com +NB_LETSENCRYPT_EMAIL=admin@example.com +NB_LETSENCRYPT_DATA_DIR=/data/letsencrypt + +# Embedded STUN (comma-separated for multiple ports, e.g., 3478,3479) +NB_ENABLE_STUN=true +NB_STUN_PORTS=3478 +``` + + +Replace `relay-us.example.com` with your relay server's domain and `your-shared-secret-here` with the secret you generated. + + +Create `docker-compose.yml`: + +```yaml +services: + relay: + image: netbirdio/relay:latest + container_name: netbird-relay + restart: unless-stopped + ports: + - '443:443' + # Expose all ports listed in NB_STUN_PORTS + - '3478:3478/udp' + env_file: + - relay.env + volumes: + - relay_data:/data + logging: + driver: "json-file" + options: + max-size: "500m" + max-file: "2" + +volumes: + relay_data: +``` + +## Alternative: TLS with Existing Certificates + +If you have existing TLS certificates (e.g., from your own CA or a wildcard cert), replace the Let's Encrypt variables in `relay.env` with: + +```bash +# Replace the NB_LETSENCRYPT_* lines with: +NB_TLS_CERT_FILE=/certs/fullchain.pem +NB_TLS_KEY_FILE=/certs/privkey.pem +``` + +And add a certificate volume to `docker-compose.yml`: + +```yaml + volumes: + - /path/to/certs:/certs:ro + - relay_data:/data +``` + +## Start the Relay Server + +```bash +docker compose up -d +``` + +Verify it's running: + +```bash +docker compose logs -f +``` + +You should see: +``` +level=info msg="Starting relay server on :443" +level=info msg="Starting STUN server on port 3478" +``` + +If you configured Let's Encrypt, the relay generates TLS certificates lazily on the first incoming request. Trigger certificate provisioning and verify it by running: + +```bash +curl -v https://relay-us.example.com/ +``` + +A `404 page not found` response is expected — what matters is that the TLS handshake succeeds. Look for a valid Let's Encrypt certificate in the output: + +``` +* Server certificate: +* subject: CN=relay-us.example.com +* issuer: C=US; O=Let's Encrypt; CN=E8 +* SSL certificate verify ok. +``` + +## Repeat for Additional Relay Servers + +If deploying multiple relays (e.g., for different regions), repeat the steps above on each server. Use the **same `NB_AUTH_SECRET`** but update the domain name for each. + +## Update Main Server Configuration + +Now update your main NetBird server to use the external relays instead of the embedded one. + +### Edit config.yaml + +On your main server, edit the `config.yaml` file: + +```bash +cd ~/netbird # or wherever your deployment is +nano config.yaml +``` + +Remove the `authSecret` from the `server` section and add `relays` and `stuns` sections pointing to your external servers. The presence of the `relays` section disables both the embedded relay and the embedded STUN server, so the `stuns` section is required to provide external STUN addresses: + +```yaml +server: + listenAddress: ":80" + exposedAddress: "https://netbird.example.com:443" + # Remove authSecret to disable the embedded relay + # authSecret: ... + # Remove or comment out stunPorts since we're using external STUN + # stunPorts: + # - 3478 + metricsPort: 9090 + healthcheckAddress: ":9000" + logLevel: "info" + logFile: "console" + dataDir: "/var/lib/netbird" + + # External STUN servers (your relay servers) + stuns: + - uri: "stun:relay-us.example.com:3478" + proto: "udp" + - uri: "stun:relay-eu.example.com:3478" + proto: "udp" + + # External relay servers + relays: + addresses: + - "rels://relay-us.example.com:443" + - "rels://relay-eu.example.com:443" + secret: "your-shared-secret-here" + credentialsTTL: "24h" + + auth: + issuer: "https://netbird.example.com/oauth2" + # ... rest of auth config +``` + + +The `secret` under `relays` and the `NB_AUTH_SECRET` on all relay servers **must be identical**. Mismatched secrets will cause relay connections to fail silently. + + +### Update docker-compose.yml (Optional) + +If your main server was exposing STUN port 3478, you can remove it since STUN is now handled by external relays: + +```yaml + netbird-server: + image: netbirdio/netbird-server:latest + container_name: netbird-server + restart: unless-stopped + networks: [netbird] + # Remove the STUN port - no longer needed + # ports: + # - '3478:3478/udp' + volumes: + - netbird_data:/var/lib/netbird + - ./config.yaml:/etc/netbird/config.yaml + command: ["--config", "/etc/netbird/config.yaml"] +``` + +### Restart the Main Server + +```bash +docker compose down +docker compose up -d +``` + +## Verify the Configuration + +### Check Main Server Logs + +```bash +docker compose logs netbird-server +``` + +Verify that the embedded relay is disabled and your external relay addresses are listed: + +``` +INFO combined/cmd/root.go: Management: true (log level: info) +INFO combined/cmd/root.go: Signal: true (log level: info) +INFO combined/cmd/root.go: Relay: false (log level: ) +``` + +``` +Relay addresses: [rels://relay-us.example.com:443 rels://relay-eu.example.com:443] +``` + +### Check Peer Status + +Connect a NetBird client and verify that both STUN and relay services are available: + +```bash +netbird status -d +``` + +The output should list your external STUN and relay servers. All configured STUN servers will appear, but only one randomly chosen relay is used per client: + +``` +Relays: + [stun:relay-us.example.com:3478] is Available + [stun:relay-eu.example.com:3478] is Available + [rels://relay-eu.example.com:443] is Available +``` + +You can also test failover by stopping one of the relay servers and checking the status again. The client will detect the unavailable server and use the remaining one: + +``` +Relays: + [stun:relay-us.example.com:3478] is Available + [stun:relay-eu.example.com:3478] is Unavailable, reason: stun request: context deadline exceeded + [rels://relay-us.example.com:443] is Available +``` + +### Test Relay Connectivity + +You can force all peer connections through relay to verify it works end-to-end. On a client, run: + +```bash +sudo netbird service reconfigure --service-env NB_FORCE_RELAY=true +``` + +Then test connectivity to another peer (e.g., with `ping`). + +Once confirmed, switch back to normal mode. The client will attempt peer-to-peer connections first and fall back to relay only when direct connectivity isn't possible: + +```bash +sudo netbird service reconfigure --service-env NB_FORCE_RELAY=false +``` \ No newline at end of file diff --git a/src/pages/selfhosted/maintenance/scaling/set-up-external-signal.mdx b/src/pages/selfhosted/maintenance/scaling/set-up-external-signal.mdx new file mode 100644 index 00000000..125ed0bb --- /dev/null +++ b/src/pages/selfhosted/maintenance/scaling/set-up-external-signal.mdx @@ -0,0 +1,149 @@ +# Set Up External Signal Server + +import {Note, Warning} from "@/components/mdx"; + +This guide is part of the [Splitting Your Self-Hosted Deployment](/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment) guide. It covers extracting the Signal server to a dedicated machine. + +In most deployments, the embedded Signal server works well and does not need to be extracted. Consider running an external Signal server if you want to separate it from the Management server for organizational or infrastructure reasons. + +Unlike relay servers, the Signal server cannot be replicated as it maintains in-memory connection state. If you need high-availability active-active mode for both Management and Signal, this is available through an [enterprise commercial license](https://netbird.io/pricing#on-prem). + + +Changing the Signal server URL requires all clients to restart. After updating the configuration, each client must run `netbird down` followed by `netbird up` to reconnect to the new Signal server. This limitation will be addressed in a future client release. + + +## Server Requirements + +- A Linux VM with at least **1 CPU** and **1GB RAM** +- Public IP address +- A domain name pointing to the server (e.g., `signal.example.com`) +- Docker installed +- Firewall ports open: **80/tcp** (Let's Encrypt HTTP challenge) and **443/tcp** (gRPC/WebSocket client communication) + +## Create Signal Configuration + +On your signal server, create a directory and configuration: + +```bash +mkdir -p ~/netbird-signal +cd ~/netbird-signal +``` + +Like the relay, the signal server can automatically obtain TLS certificates via Let's Encrypt. + + +Replace `signal.example.com` with your signal server's domain. + + +Create `signal.env` with your signal settings: + +```bash +NB_PORT=443 +NB_LOG_LEVEL=info + +# TLS via Let's Encrypt (automatic certificate provisioning) +NB_LETSENCRYPT_DOMAIN=signal.example.com +``` + +Create `docker-compose.yml`: + +```yaml +services: + signal: + image: netbirdio/signal:latest + container_name: netbird-signal + restart: unless-stopped + ports: + - '443:443' + - '80:80' + env_file: + - signal.env + volumes: + - signal_data:/var/lib/netbird + logging: + driver: "json-file" + options: + max-size: "500m" + max-file: "2" + +volumes: + signal_data: +``` + +## Alternative: TLS with Existing Certificates + +If you have existing TLS certificates, replace the Let's Encrypt variable in `signal.env` with: + +```bash +# Replace the NB_LETSENCRYPT_DOMAIN line with: +NB_CERT_FILE=/certs/fullchain.pem +NB_CERT_KEY=/certs/privkey.pem +``` + +And add a certificate volume to `docker-compose.yml`: + +```yaml + volumes: + - /path/to/certs:/certs:ro + - signal_data:/var/lib/netbird +``` + +## Start the Signal Server + +```bash +docker compose up -d +``` + +Verify it's running: + +```bash +docker compose logs -f +``` + +If you configured Let's Encrypt, trigger certificate provisioning with an HTTPS request: + +```bash +curl -v https://signal.example.com/ +``` + +Confirm the certificate was issued: + +``` +* Server certificate: +* subject: CN=signal.example.com +* issuer: C=US; O=Let's Encrypt; CN=E8 +* SSL certificate verify ok. +``` + +## Update Main Server Configuration + +On your main server, add `signalUri` to `config.yaml`. This disables the embedded Signal server: + +```yaml +server: + # ... existing settings ... + + # External signal server + signalUri: "https://signal.example.com:443" +``` + +Restart the main server: + +```bash +docker compose down +docker compose up -d +``` + +## Verify Signal Extraction + +Check the main server logs to confirm the embedded Signal is disabled: + +```bash +docker compose logs netbird-server +``` + +``` +INFO combined/cmd/root.go: Management: true (log level: info) +INFO combined/cmd/root.go: Signal: false (log level: ) +INFO combined/cmd/root.go: Relay: false (log level: ) +``` \ No newline at end of file diff --git a/src/pages/selfhosted/maintenance/upgrade.mdx b/src/pages/selfhosted/maintenance/upgrade.mdx index 1e8d57f3..e64d405f 100644 --- a/src/pages/selfhosted/maintenance/upgrade.mdx +++ b/src/pages/selfhosted/maintenance/upgrade.mdx @@ -46,17 +46,29 @@ To upgrade NetBird to the latest version: 2. Review the release notes (see above) for any breaking changes. 3. Pull the latest NetBird docker images: ```bash - docker compose pull management dashboard signal relay + docker compose pull netbird-server dashboard ``` 4. Restart the NetBird containers with the new images: ```bash - docker compose up -d --force-recreate management dashboard signal relay + docker compose up -d --force-recreate netbird-server dashboard ``` For upgrades from older versions (pre-v0.26.0), see the [Legacy upgrade notes](#legacy-self-hosting-with-zitadel-idp). +### Legacy Setup (Separate Containers) + +If your deployment uses the older setup with separate containers (`management`, `signal`, `relay`, `coturn`), pull and recreate those containers instead: + +```bash +docker compose pull management dashboard signal relay +``` + +```bash +docker compose up -d --force-recreate management dashboard signal relay +``` + ## Get In Touch Feel free to ping us on [Slack](/slack-url) if you have any questions. diff --git a/src/pages/selfhosted/migration/enable-reverse-proxy.mdx b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx new file mode 100644 index 00000000..596994d7 --- /dev/null +++ b/src/pages/selfhosted/migration/enable-reverse-proxy.mdx @@ -0,0 +1,318 @@ +# Migration Guide: Enable Reverse Proxy Feature + +This guide walks you through adding the NetBird Reverse Proxy to an existing self-hosted deployment. By the end, you'll have a `netbird-proxy` container running alongside your existing services, ready to expose internal applications to the public internet. + + +**Who is this guide for?** This migration guide is for existing self-hosted users who: +- Already have a working NetBird deployment (management server, dashboard, signal, relay) +- Want to enable the [Reverse Proxy](/manage/reverse-proxy) feature to expose internal services publicly +- Are running their services via Docker Compose + + +## Why Traefik is required + +The NetBird proxy container manages its own TLS certificates (via Let's Encrypt or static files). This means the reverse proxy sitting in front of it **must not terminate TLS** - it needs to pass raw TLS connections through to the proxy container untouched. + +This capability is called **TLS passthrough**, and among common reverse proxies, **only Traefik supports it** via its TCP routers. Other reverse proxies (Nginx, Caddy, Nginx Proxy Manager) terminate TLS themselves and cannot forward the raw encrypted connection, which breaks the proxy's certificate management. + +If your current deployment uses a reverse proxy other than Traefik, you'll need to switch before enabling this feature. See [Switching to Traefik](/selfhosted/reverse-proxy#traefik) for instructions. + +## Overview of changes + +### What you're adding + +- **`netbird-proxy` container** - a new service in your Docker Compose stack that handles TLS termination, certificate provisioning, and traffic forwarding for reverse proxy services +- **Traefik TCP labels** - routing rules that tell Traefik to pass TLS connections through to the proxy container +- **Wildcard DNS record** - so that all service subdomains (e.g., `myapp.proxy.example.com`) resolve to your server +- **Proxy access token** - generated via the management CLI, used by the proxy to authenticate with the management server + +### What stays the same + +- Your existing `netbird-server`, `dashboard`, `signal`, and `relay` services are unchanged +- Your `management.json` and other configuration files require no modifications — **unless** you use an external identity provider (not the embedded IdP). See [Configure SSO for external identity providers](#configure-sso-for-external-identity-providers) below. +- Existing peers, networks, and access policies are unaffected + +## Prerequisites + +Before starting, ensure you have: + +- **Traefik** as your reverse proxy (see [Why Traefik is required](#why-traefik-is-required) above) +- **Latest `netbird-server` image** - pull the latest version to ensure the management CLI supports 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 + + +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. + +- **Port 443 accessible** - the proxy needs this for ACME TLS-ALPN-01 challenges (certificate provisioning) + +## Migration steps + +### Step 1: Backup current configuration + +```bash +# Create a backup directory +mkdir -p netbird-backup-$(date +%Y%m%d) +cd netbird-backup-$(date +%Y%m%d) + +# Backup configuration files +cp ../docker-compose.yml . +cp ../management.json . +cp ../*.env . 2>/dev/null || echo "No .env files found" +``` + +### Step 2: Generate a proxy access token + +The proxy authenticates with the management server using an access token. Generate one using the management CLI: + +```bash +docker exec -it netbird-server netbird-mgmt token create --name "my-proxy" +``` + +This outputs a token in the format `nbx_...` (40 characters). **Save the token immediately** - it is only displayed once. The management server stores only a SHA-256 hash. + +You can manage tokens later with: + +```bash +# List all tokens +docker exec -it netbird-server netbird-mgmt token list + +# Revoke a token by ID +docker exec -it netbird-server netbird-mgmt token revoke +``` + +### Step 3: Add the proxy service to docker-compose.yml + +Add the following service to your `docker-compose.yml`. Replace the placeholder values with your actual token and domains: + +```yaml +netbird-proxy: + image: netbirdio/netbird-proxy:latest + container_name: netbird-proxy + restart: unless-stopped + networks: [netbird] + environment: + - NB_PROXY_TOKEN=nbx_your_token_here + - NB_PROXY_DOMAIN=proxy.example.com + - NB_PROXY_MANAGEMENT_ADDRESS=https://netbird.example.com:443 + - NB_PROXY_ACME_CERTIFICATES=true + labels: + - traefik.enable=true + - traefik.tcp.routers.netbird-proxy.rule=HostSNI(`*.proxy.example.com`) + - traefik.tcp.routers.netbird-proxy.entrypoints=websecure + - traefik.tcp.routers.netbird-proxy.tls.passthrough=true + - traefik.tcp.routers.netbird-proxy.priority=1 + - traefik.tcp.services.netbird-proxy.loadbalancer.server.port=8443 + logging: + driver: "json-file" + options: + max-size: "500m" + max-file: "2" +``` + +The Traefik labels configure a **TCP router** that: +- Matches any request to `*.proxy.example.com` via SNI (Server Name Indication) +- Uses the `websecure` entrypoint (port 443) +- Passes the TLS connection through **without termination** (`tls.passthrough=true`) +- Uses `priority=1` to avoid intercepting traffic meant for the main NetBird HTTP routers on the same entrypoint +- Forwards traffic to the proxy container on port 8443 + + +Replace `proxy.example.com` in both the `NB_PROXY_DOMAIN` environment variable and the Traefik `HostSNI` rule with your actual proxy domain. These must match. + + +### Step 4: Set up wildcard DNS + +Create a wildcard DNS record pointing to the server running your NetBird stack: + +``` +*.proxy.example.com → +``` + +This 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. + +### Step 5: Apply changes + +```bash +# Pull the new image +docker compose pull netbird-proxy + +# Start the proxy alongside existing services +docker compose up -d + +# Verify all services are running +docker compose ps + +# Check proxy logs +docker compose logs -f netbird-proxy +``` + +You should see log messages indicating the proxy has connected to the management server and is ready to serve traffic. + +### Step 6: Verify in the dashboard + +Once the proxy connects to the management server: + +1. Open your NetBird dashboard +2. Navigate to **Reverse Proxy** > **Services** +3. Click **Add Service** +4. In the domain selector, you should see your proxy domain (e.g., `proxy.example.com`) with a **Cluster** badge + +If the domain appears, the proxy is connected and ready. You can now [create your first service](/manage/reverse-proxy#quick-start). + +## Configure SSO for external identity providers + +### Who this applies to + +This section applies to deployments using a **standalone external identity provider** (Auth0, Okta, Keycloak, Zitadel, etc.) instead of the built-in embedded IdP (Dex). If you deployed using the quickstart script with default settings, you are using the embedded IdP and can skip this section. + +### Why this is needed + +The reverse proxy SSO feature authenticates users through an OAuth2/OIDC flow that redirects through a callback endpoint on the management server (`/api/reverse-proxy/callback`). The embedded IdP registers this callback automatically, but external IdPs need it configured manually. Without this configuration, SSO authentication on reverse proxy services will silently fail. + +### Option A: Quick fix (keep your external IdP) + +If you want to keep using your current external identity provider, follow these three steps: + +#### Step 1: Add callback URL to management.json + +Add the `AuthCallbackURL` field to the `HttpConfig` section of your `management.json`: + +```json +"HttpConfig": { + ...existing fields..., + "AuthCallbackURL": "https:///api/reverse-proxy/callback" +} +``` + +Replace `` with your NetBird management server domain (the same domain used for the dashboard). + +#### Step 2: Register callback in your IdP + +In your identity provider's application settings, add the following URL as an allowed redirect URI / callback URL: + +``` +https:///api/reverse-proxy/callback +``` + +This is in addition to any existing redirect URIs (like `/auth` or `/silent-auth`). + +Where to find this setting in common providers: + +| Provider | Where to add the redirect URI | +|----------|-------------------------------| +| Auth0 | Application > Settings > Allowed Callback URLs | +| Okta | Application > General > Login redirect URIs | +| Keycloak | Client > Settings > Valid redirect URIs | +| Zitadel | Application > Redirect Settings > Redirect URIs | +| Generic OIDC | Refer to your provider's documentation | + +#### Step 3: Restart management server + +Restart the management service to pick up the configuration change: + +```bash +docker compose restart netbird-management +``` + +### Option B: Migrate to the embedded IdP (recommended) + +The embedded IdP (Dex) handles the reverse proxy callback registration automatically — no manual configuration needed. If you want a simpler setup, consider migrating to the embedded IdP. + +With the embedded IdP, external identity providers can still be used as **connectors** alongside local authentication. This means your users can continue to sign in with their existing accounts (Google, Okta, Keycloak, etc.) while the embedded IdP manages the OIDC layer. + +See the [Identity Providers page](/selfhosted/identity-providers) for instructions on adding external IdPs as connectors. + + +Migrating from a standalone external IdP to the embedded IdP with your IdP as a connector requires user ID migration. See the [Migration Guide](/selfhosted/identity-providers#migration-guide-and-backwards-compatibility) or contact [support@netbird.io](mailto:support@netbird.io) for assistance. + + +### Verification + +After configuring SSO for your external identity provider, verify it works: + +1. Create a reverse proxy service with **SSO authentication** enabled +2. Open the service URL in an incognito/private browser window +3. Confirm you are redirected to your IdP login page +4. After authenticating, confirm you are redirected back to the service and can access it + +If the redirect fails or you see an error from your IdP, double-check that the callback URL is correctly registered in both `management.json` and your identity provider's settings. + +## For users not on Traefik + +If your self-hosted deployment currently uses Nginx, Caddy, or another reverse proxy, you'll need to switch to Traefik before enabling the Reverse Proxy feature. See the [Traefik setup instructions](/selfhosted/reverse-proxy#traefik) for a step-by-step guide on configuring Traefik for your NetBird deployment. + +## Environment variable reference + +| Variable | Required | Description | Default | +|----------|----------|-------------|---------| +| `NB_PROXY_TOKEN` | Yes | Access token generated via `netbird-mgmt token create`. 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_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` | +| `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` | + +## Troubleshooting + +### Certificate provisioning failures + +**Symptom**: Services stay in `certificate_pending` or move to `certificate_failed` status. + +**Checklist**: +1. Verify port 443 is accessible from the internet (required for `tls-alpn-01` challenge) +2. Ensure the wildcard DNS record resolves correctly: `dig myapp.proxy.example.com` +3. Check proxy logs for ACME errors: `docker compose logs netbird-proxy | grep -i acme` +4. If using `http-01` challenge type, ensure port 80 is also accessible + +### TLS passthrough not working + +**Symptom**: The proxy starts but services return TLS errors or Traefik's default certificate. + +**Checklist**: +1. Verify Traefik labels include `tls.passthrough=true` +2. Confirm the router is configured as a **TCP** router (not HTTP) - labels should use `traefik.tcp.routers`, not `traefik.http.routers` +3. Check that the `HostSNI` rule matches your proxy domain with the wildcard (`*.proxy.example.com`) +4. Verify the TCP router has `priority=1` to prevent it from intercepting traffic meant for the main NetBird HTTP routers +5. Ensure the `websecure` entrypoint is configured in your Traefik configuration +6. Restart Traefik after adding the proxy container: `docker compose restart traefik` + +### Port conflicts + +**Symptom**: The proxy container fails to start with an address-in-use error. + +**Solution**: The proxy listens on port 8443 inside the container. If another service uses port 8443 on the same Docker network, change `NB_PROXY_ADDRESS` to a different port and update the Traefik label `loadbalancer.server.port` to match. + +## Rollback procedure + +If you need to remove the proxy and revert to your previous configuration: + +```bash +# Stop all services +docker compose down + +# Restore your backup +cd netbird-backup-YYYYMMDD +cp docker-compose.yml ../ + +# Restart without the proxy +cd .. +docker compose up -d +``` + +You can also revoke the proxy token to prevent the proxy from reconnecting: + +```bash +docker exec -it netbird-server netbird-mgmt token list +docker exec -it netbird-server netbird-mgmt token revoke +``` + +## Additional resources + +- [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 diff --git a/src/pages/selfhosted/reverse-proxy.mdx b/src/pages/selfhosted/reverse-proxy.mdx index d74745a0..abf0fd2b 100644 --- a/src/pages/selfhosted/reverse-proxy.mdx +++ b/src/pages/selfhosted/reverse-proxy.mdx @@ -1,6 +1,6 @@ # Reverse Proxy Configuration -NetBird includes a built-in Caddy reverse proxy that handles TLS certificates automatically. However, if you already have an existing reverse proxy (Traefik, Nginx, etc.), you can configure NetBird to work with it instead. +NetBird includes a built-in Traefik reverse proxy that handles TLS certificates automatically via Let's Encrypt. However, if you already have an existing reverse proxy (Nginx, Caddy, etc.), you can configure NetBird to work with it instead. Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying. @@ -14,8 +14,8 @@ The `getting-started.sh` script supports multiple reverse proxy configurations. ``` Which reverse proxy will you use? - [0] Built-in Caddy (recommended - automatic TLS) - [1] Traefik (labels added to containers) + [0] Traefik (recommended - automatic TLS, included in Docker Compose) + [1] Existing Traefik (labels for external Traefik instance) [2] Nginx (generates config template) [3] Nginx Proxy Manager (generates config + instructions) [4] External Caddy (generates Caddyfile snippet) diff --git a/src/pages/selfhosted/selfhosted-guide.mdx b/src/pages/selfhosted/selfhosted-guide.mdx index 05ab4664..8a5195f7 100644 --- a/src/pages/selfhosted/selfhosted-guide.mdx +++ b/src/pages/selfhosted/selfhosted-guide.mdx @@ -201,7 +201,7 @@ docker compose logs dashboard ## Advanced: Running NetBird behind an existing reverse-proxy -If you already have a reverse proxy (Traefik, Nginx, Caddy, etc.), you can configure NetBird to work with it instead of using the built-in Caddy. +If you already have a reverse proxy (Nginx, Caddy, etc.), you can configure NetBird to work with it instead of using the built-in Traefik. Not all reverse proxies are supported as NetBird uses *gRPC* for various components. Your reverse proxy must support HTTP/2 and gRPC proxying. diff --git a/src/pages/selfhosted/selfhosted-quickstart.mdx b/src/pages/selfhosted/selfhosted-quickstart.mdx index a6c85b40..77d6401b 100644 --- a/src/pages/selfhosted/selfhosted-quickstart.mdx +++ b/src/pages/selfhosted/selfhosted-quickstart.mdx @@ -13,14 +13,13 @@ This is the quickest way to try self-hosted NetBird. It should take around 5 min ## Infrastructure requirements - 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. +- A **public domain** name that resolves to the VM's public IP address. ## Software requirements - Docker with docker-compose plugin ([Docker installation guide](https://docs.docker.com/engine/install/)) or Docker with docker-compose version 2 or higher -- [jq](https://jqlang.github.io/jq/) — install with `sudo apt install jq` or `sudo yum install jq` -- [curl](https://curl.se/) — install with `sudo apt install curl` or `sudo yum install curl` -Usually available in the official repositories and can be installed with `sudo apt install curl` or `sudo yum install curl` +- [jq](https://jqlang.github.io/jq/) - install with `sudo apt install jq` or `sudo yum install jq` +- [curl](https://curl.se/) - install with `sudo apt install curl` or `sudo yum install curl` ## Installation Script @@ -30,8 +29,8 @@ Download and run the installation script: curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash ``` -Once finished, you can manage the resources via `docker compose`. The quick start script generates a full, production-ready NetBird installation. If you'd like to customize the install or gain a better understanding of the files -generated by the script, including the docker compose file, please refer to our [Configuration files](/selfhosted/configuration-files) guide. +Once finished, you can manage the resources via `docker compose`. The quick start script generates a full, production-ready NetBird installation. If you'd like to customize the install or gain a better understanding of the files +generated by the script, including the docker compose file, please refer to our [Configuration files](/selfhosted/configuration-files) guide. ### Reverse Proxy Selection @@ -39,8 +38,8 @@ The script will prompt you to select a reverse proxy option: ``` Which reverse proxy will you use? - [0] Built-in Caddy (recommended - automatic TLS) - [1] Traefik (labels added to containers) + [0] Traefik (recommended - automatic TLS, included in Docker Compose) + [1] Existing Traefik (labels for external Traefik instance) [2] Nginx (generates config template) [3] Nginx Proxy Manager (generates config + instructions) [4] External Caddy (generates Caddyfile snippet) @@ -49,20 +48,32 @@ Which reverse proxy will you use? Enter choice [0-5] (default: 0): ``` -**For this quickstart guide, select option `[0]` (Built-in Caddy)** - just press Enter to use the default. This option handles TLS certificates automatically via Let's Encrypt and requires no additional configuration. +**For this quickstart guide, select option `[0]` (Traefik)** - just press Enter to use the default. This option includes a Traefik container in the Docker Compose that handles TLS certificates automatically via Let's Encrypt and requires no additional configuration. If you already have a reverse proxy (Traefik, Nginx, etc.) and want to use it instead, the script will guide you through the setup. See the [Reverse Proxy Configuration](/selfhosted/reverse-proxy) guide for detailed instructions on each option. +### Generated Files + +The script generates the following files: + +| File | Description | +|------|-------------| +| `docker-compose.yml` | Docker Compose configuration with all services | +| `config.yaml` | Combined server configuration (management, signal, relay, STUN) | +| `dashboard.env` | Environment variables for the dashboard container | + +For options 2-4, additional configuration files are generated (e.g., `nginx-netbird.conf`, `caddyfile-netbird.txt`, or `npm-advanced-config.txt`). + ### Example Output ```bash root@selfhosted-1:~/netbird# bash getting-started.sh Which reverse proxy will you use? - [0] Built-in Caddy (recommended - automatic TLS) - [1] Traefik (labels added to containers) + [0] Traefik (recommended - automatic TLS, included in Docker Compose) + [1] Existing Traefik (labels for external Traefik instance) [2] Nginx (generates config template) [3] Nginx Proxy Manager (generates config + instructions) [4] External Caddy (generates Caddyfile snippet) @@ -73,14 +84,14 @@ Rendering initial files... Starting NetBird services -[+] Running 5/5 - ✔ Network netbird Created - ✔ Container netbird-dashboard Started - ✔ Container netbird-management Started - ✔ Container netbird-relay Started - ✔ Container netbird-signal Started - ✔ Container netbird-caddy Started -Waiting for Management server to become ready . . done +[+] up 6/6 + ✔ Network combined_netbird Created 0.1s + ✔ Volume combined_netbird_data Created 0.0s + ✔ Volume combined_netbird_traefik_letsencrypt Created 0.0s + ✔ Container netbird-server Created 0.1s + ✔ Container netbird-traefik Created 0.1s + ✔ Container netbird-dashboard Created 0.1s +Waiting for NetBird server to become ready . . . done Done! @@ -112,7 +123,7 @@ The `/setup` page is only accessible when no users exist. After creating the fir ## Add More Users NetBird includes built-in local user management powered by an embedded Dex server, allowing you to create and manage users directly from the Dashboard without requiring an external identity provider. You can also add external identity providers for SSO authentication alongside local users. - + --- ## Troubleshoot - **I can't access the `/setup` page** - + The setup page is only available when no users exist. If you've already created a user, go to the main login page instead. - **I forgot my admin password** - + You can create a new user via the API using a PAT (Personal Access Token) from an existing admin, or reset the database to start fresh. - **SSO provider not appearing on login page** - + Check that the connector is properly configured in **Settings** → **Identity Providers**. Ensure the redirect URL is correctly configured in your IdP. For more troubleshooting help, see the [Troubleshooting guide](/selfhosted/troubleshooting).