sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-18 08:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Reverse Proxy documentation and update self-hosted quickstart (#594)

Browse Source 
- Add Reverse Proxy docs: overview, custom domains, authentication, access logs
- Add Reverse Proxy section to sidebar navigation
- Update self-hosted quickstart for new getting-started.sh (Traefik default, combined server)
This commit is contained in:
shuuri-labs
2026-02-13 19:07:01 +01:00
committed by GitHub
parent 320e9fdcaf
commit 432602e35e
23 changed files with 2031 additions and 634 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
src/pages/manage/reverse-proxy/access-logs.mdx Normal file
View File

@@ -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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/access-logs-table.png" alt="Proxy Events table showing reverse proxy access log entries" className="imagewrapper"/>
</p>
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

163
src/pages/manage/reverse-proxy/authentication.mdx Normal file
View File

@@ -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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png" alt="Authentication tab showing all available authentication methods" className="imagewrapper"/>
</p>
## 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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/auth-sso-modal.png" alt="SSO configuration modal with group selection" className="imagewrapper"/>
</p>
**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
<Note>
**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.
</Note>
**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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/auth-password-modal.png" alt="Password configuration modal" className="imagewrapper"/>
</p>
**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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/auth-pin-modal.png" alt="PIN Code configuration modal" className="imagewrapper"/>
</p>
**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.
<Note>
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.
</Note>
<p>
<img src="/docs-static/img/manage/reverse-proxy/auth-no-auth-warning.png" alt="Warning dialog displayed when saving a service without authentication" className="imagewrapper"/>
</p>
**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).
<Note>
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).
</Note>
### 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

166
src/pages/manage/reverse-proxy/custom-domains.mdx Normal file
View File

@@ -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**.
<p>
<img src="/docs-static/img/manage/reverse-proxy/custom-domains-add.png" alt="Add Domain modal showing domain name and proxy cluster fields" className="imagewrapper"/>
</p>
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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/custom-domains-validation.png" alt="Domain validation status showing CNAME record details" className="imagewrapper"/>
</p>
NetBird performs a CNAME lookup on `validation.<your-domain>` 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.
<Note>
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.
</Note>
## 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.
<Note>
Before deleting a custom domain, make sure no active services are using it. Services referencing a deleted domain will no longer route traffic correctly.
</Note>
## 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.<your-domain>` 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

281
src/pages/manage/reverse-proxy/index.mdx Normal file
View File

@@ -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.
<Note>
**Availability:** Reverse Proxy is currently only available for **self-hosted** deployments and is currently in **beta**. **Cloud** support is coming soon.
</Note>
<Note>
**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.
</Note>
## 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. |
<Note>
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.
</Note>
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.
<Note>
**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).
</Note>
**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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-details.png" alt="Add Service modal showing the Details tab" className="imagewrapper"/>
</p>
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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/reverse-proxy-add-target.png" alt="Add Target configuration modal" className="imagewrapper"/>
</p>
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.
<p>
<img src="/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-auth.png" alt="Add Service modal showing the Authentication tab" className="imagewrapper"/>
</p>
- 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.
<Note>
You can enable multiple authentication methods simultaneously. Users will be able to choose their preferred method when accessing the service.
</Note>
### Step 4: Configure advanced settings
Switch to the **Settings** tab to adjust advanced proxy behavior.
<p>
<img src="/docs-static/img/manage/reverse-proxy/reverse-proxy-add-service-settings.png" alt="Add Service modal showing the Settings tab" className="imagewrapper"/>
</p>
- **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
<div float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</div>
- 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