Self-Hosted Deployment Configuration Files Reference

This page provides a comprehensive reference for all configuration files used when self-hosting NetBird with the getting-started.sh deployment method. Understanding these files helps you customize your deployment, troubleshoot issues, and integrate with existing infrastructure.

Overview

A standard NetBird self-hosted deployment uses the following configuration files:

File Locations

After running the installation script, configuration files are located in the directory where you ran the script (typically ~/netbird/ or the current working directory):

./
├── docker-compose.yml
├── management.json
├── relay.env
├── dashboard.env
└── Caddyfile          # Only when using built-in Caddy

docker-compose.yml

The Docker Compose file defines all NetBird services, their dependencies, networking, and volumes.

Services Overview

Default Settings

The compose file includes these defaults applied to all services:

x-default: &default
  restart: 'unless-stopped'
  logging:
    driver: 'json-file'
    options:
      max-size: '500m'
      max-file: '2'

Dashboard Service

The dashboard provides the web interface for NetBird management.

With built-in Caddy (default):

dashboard:
  image: netbirdio/dashboard:latest
  container_name: netbird-dashboard
  restart: unless-stopped
  networks: [netbird]
  env_file:
    - ./dashboard.env
  logging:
    driver: "json-file"
    options:
      max-size: "500m"
      max-file: "2"

With external reverse proxy (exposed ports):

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
  logging:
    driver: "json-file"
    options:
      max-size: "500m"
      max-file: "2"

Management Service

The management service is the core of NetBird, handling peer registration, authentication, and network coordination.

With built-in Caddy (default):

management:
  image: netbirdio/management:latest
  container_name: netbird-management
  restart: unless-stopped
  networks: [netbird]
  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",
  ]
  logging:
    driver: "json-file"
    options:
      max-size: "500m"
      max-file: "2"

With external reverse proxy (exposed ports):

management:
  image: netbirdio/management:latest
  container_name: netbird-management
  restart: unless-stopped
  networks: [netbird]
  ports:
    - '127.0.0.1:8081:80'
  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",
  ]
  logging:
    driver: "json-file"
    options:
      max-size: "500m"
      max-file: "2"

To use an external database, add environment variables:

  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

Command-Line Flags

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):

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):

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"

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):

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):

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 relay service is configured via the relay.env file. See the relay.env section for detailed configuration options.

STUN Server (Embedded in Relay)

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 for coturn configuration details.

Volume Configuration

management.json

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 for configuration details.

Configuration Sections

The management.json file for getting-started.sh deployments uses these sections:

Complete Structure

{
    "Stuns": [...],
    "Relay": {...},
    "Signal": {...},
    "Datadir": "/var/lib/netbird",
    "DataStoreEncryptionKey": "...",
    "EmbeddedIdP": {
        "Enabled": true,
        "Issuer": "https://your-domain/oauth2",
        "DashboardRedirectURIs": [...]
    }
}

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.

"Stuns": [
    {
        "Proto": "udp",
        "URI": "stun:netbird.example.com:3478",
        "Username": "",
        "Password": null
    }
]

Relay Section

Configures the NetBird relay server connection for NAT traversal.

What does the relay service do?

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.

• 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

"Relay": {
    "Addresses": ["rels://netbird.example.com:443"],
    "CredentialsTTL": "24h",
    "Secret": "your-relay-secret"
}

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)

"Signal": {
    "Proto": "https",
    "URI": "netbird.example.com:443",
    "Username": "",
    "Password": null
}

ReverseProxy Section

Configures trusted reverse proxies for proper client IP detection.

"ReverseProxy": {
    "TrustedHTTPProxies": [],
    "TrustedHTTPProxiesCount": 0,
    "TrustedPeers": ["0.0.0.0/0"]
}

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:

• 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

Where is the data stored?

"StoreConfig": {
    "Engine": "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

See Management 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.

"EmbeddedIdP": {
    "Enabled": true,
    "Issuer": "https://netbird.example.com/oauth2",
    "DashboardRedirectURIs": [
        "https://netbird.example.com/nb-auth",
        "https://netbird.example.com/nb-silent-auth"
    ]
}

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

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.

# 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

dashboard.env

Environment configuration for the dashboard service.

Dashboard Architecture

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.

# Endpoints
NETBIRD_MGMT_API_ENDPOINT=https://netbird.example.com
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://netbird.example.com

# OIDC - using embedded IdP
AUTH_AUDIENCE=netbird-dashboard
AUTH_CLIENT_ID=netbird-dashboard
AUTH_CLIENT_SECRET=
AUTH_AUTHORITY=https://netbird.example.com/oauth2
USE_AUTH0=false
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)
NGINX_SSL_PORT=443
LETSENCRYPT_DOMAIN=none

Endpoint Configuration

Authentication Configuration

Embedded Nginx Configuration

The dashboard container's embedded nginx server can be configured using these environment variables. These settings control how the dashboard serves its web UI.

Common Configuration Scenarios

Using an External Database

To use PostgreSQL instead of SQLite:

1. Update management.json:

"StoreConfig": {
    "Engine": "postgres"
}

2. Set the connection string in docker-compose.yml:

management:
  environment:
    - NETBIRD_STORE_ENGINE_POSTGRES_DSN=postgres://user:password@host:5432/netbird?sslmode=disable

See Management Postgres Store for detailed setup.

Disabling Anonymous Metrics

In docker-compose.yml, update the management command:

management:
  command: [
    "--port", "80",
    "--disable-anonymous-metrics=true",
    # ... other flags
  ]

Custom Relay Configuration

To use multiple relay servers, update management.json:

"Relay": {
    "Addresses": [
        "rels://relay1.example.com:443",
        "rels://relay2.example.com:443"
    ],
    "CredentialsTTL": "24h",
    "Secret": "shared-secret"
}

Each relay server must use the same NB_AUTH_SECRET. Use rels:// for TLS (port 443) or rel:// for unencrypted (port 80).

Behind a Reverse Proxy

When running behind your own reverse proxy (Traefik, Nginx, etc.):

1. Set LETSENCRYPT_DOMAIN=none in dashboard.env
2. Configure trusted proxies in management.json:

"ReverseProxy": {
    "TrustedHTTPProxies": ["10.0.0.1"],
    "TrustedHTTPProxiesCount": 1,
    "TrustedPeers": ["10.0.0.0/8"]
}

See Reverse Proxy Configuration for detailed templates.

Configuring External TURN Servers

To use external TURN servers (e.g., coturn deployed separately):

"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
}

See Also

• Self-hosting Quickstart Guide - Get started quickly with default settings
• Reverse Proxy Configuration - Traefik, Nginx, Caddy setup
• Management SQLite Store - SQLite database details
• Management Postgres Store - PostgreSQL setup