Environment Variables Configuration

This page provides a comprehensive reference for all environment variables available when self-hosting NetBird. Environment variables allow you to configure the Management Server, Signal Server, Relay Server (including the embedded STUN server), and Dashboard services.

Environment variables set in your setup.env file are used by the configure.sh script to generate the final configuration files. Changes to setup.env require re-running ./configure.sh to take effect.

Overview

NetBird uses two types of environment variables:

Setup Variables (NETBIRD_ prefix) - Used in docker-compose templates and setup.env for initial configuration
Runtime Variables (NB_ prefix) - Can override CLI flags at runtime using the pattern --flag-name → NB_FLAG_NAME

Core Setup Variables

These variables are set in your setup.env file before running the configuration script.

Domain and Network

Variable	Description	Example
`NETBIRD_DOMAIN`	Your NetBird domain name	`netbird.example.com`
`NETBIRD_LETSENCRYPT_EMAIL`	Email for Let's Encrypt certificates	`admin@example.com`
`NETBIRD_DISABLE_LETSENCRYPT`	Disable automatic Let's Encrypt	`true`

Port Configuration

Variable	Default	Description
`NETBIRD_MGMT_API_PORT`	`33073`	Management API port
`NETBIRD_SIGNAL_PORT`	`10000`	Signal server port
`NETBIRD_RELAY_PORT`	`33080`	Relay server port
`NGINX_SSL_PORT`	`443`	Dashboard HTTPS port

STUN Configuration

The default quickstart deployment uses the relay service's embedded STUN server. The variables below configure STUN functionality within the relay container via relay.env.

Variable	Default	Description
`NB_ENABLE_STUN`	`true`	Enable embedded STUN server in relay
`NB_STUN_PORTS`	`3478`	STUN server UDP ports
`NB_STUN_LOG_LEVEL`	`info`	STUN server log level

Management Server Variables

Database Configuration

Variable	Default	Description
`NETBIRD_STORE_CONFIG_ENGINE`	`sqlite`	Store engine: `sqlite`, `postgres`, or `mysql`
`NETBIRD_STORE_ENGINE_POSTGRES_DSN`	-	PostgreSQL connection string
`NETBIRD_STORE_ENGINE_MYSQL_DSN`	-	MySQL connection string
`NETBIRD_DATASTORE_ENC_KEY`	Auto-generated	Encryption key for sensitive data

See Management Postgres Store for PostgreSQL setup details.

Single Account Mode

Variable	Default	Description
`NETBIRD_MGMT_SINGLE_ACCOUNT_MODE_DOMAIN`	-	Domain for single account mode

NetBird runs in single account mode by default since v0.10.1. All users joining your self-hosted instance will be part of the same account/network.

Relay Configuration

Variable	Description
`NETBIRD_RELAY_ENDPOINT`	Relay server endpoint URL
`NETBIRD_RELAY_AUTH_SECRET`	Shared authentication secret for relay

Signal Configuration

Variable	Description
`NETBIRD_SIGNAL_PROTOCOL`	Protocol: `http` or `https`

DNS Configuration

Variable	Default	Description
`NETBIRD_MGMT_DNS_DOMAIN`	`netbird.selfhosted`	DNS domain for peer resolution

TLS/Certificates

Variable	Description
`NETBIRD_MGMT_API_CERT_FILE`	Path to TLS certificate file
`NETBIRD_MGMT_API_CERT_KEY_FILE`	Path to TLS certificate key file

Metrics and Analytics

Variable	Default	Description
`NETBIRD_DISABLE_ANONYMOUS_METRICS`	`false`	Disable anonymous usage metrics

Runtime Environment Variables (NB_ prefix)

These variables can override CLI flags at runtime. The naming convention is NB_<FLAG_NAME> where the flag name is uppercased and hyphens are replaced with underscores.

Management Server Runtime

Variable	Description
`NB_PORT`	Server port (overrides `--port`)
`NB_DATADIR`	Data directory (overrides `--datadir`)
`NB_CONFIG`	Config file path (overrides `--config`)
`NB_LOG_LEVEL`	Log level: `debug`, `info`, `warn`, `error`
`NB_LOG_FILE`	Log file path
`NB_METRICS_PORT`	Prometheus metrics port
`NB_LETSENCRYPT_DOMAIN`	Let's Encrypt domain
`NB_CERT_FILE`	TLS certificate file
`NB_CERT_KEY`	TLS certificate key file
`NB_DNS_DOMAIN`	DNS domain for peers
`NB_DISABLE_GEOLITE_UPDATE`	Disable GeoLite database updates

Advanced Runtime Variables

Variable	Description
`NB_EVENT_ACTIVITY_LOG_ENABLED`	Enable activity log events
`NB_GET_ACCOUNT_BUFFER_INTERVAL`	Account buffer interval duration
`NB_SQL_MAX_OPEN_CONNS`	Maximum SQL database connections
`NB_STORE_TRANSACTION_TIMEOUT`	Store transaction timeout
`NB_API_RATE_LIMITING_ENABLED`	Enable API rate limiting
`NB_API_RATE_LIMITING_RPM`	Rate limit requests per minute
`NB_API_RATE_LIMITING_BURST`	Rate limit burst size
`NETBIRD_METRICS_INTERVAL_IN_SECONDS`	Metrics push interval

Signal Server Variables

Runtime Variables

Variable	Description
`NB_PORT`	Signal server port
`NB_METRICS_PORT`	Prometheus metrics port
`NB_SSL_DIR`	SSL certificates directory
`NB_LETSENCRYPT_DOMAIN`	Let's Encrypt domain
`NB_CERT_FILE`	TLS certificate file
`NB_CERT_KEY`	TLS certificate key file
`NB_LOG_LEVEL`	Log level
`NB_LOG_FILE`	Log file path

Relay Server Variables

Setup Variables

Variable	Description
`NETBIRD_RELAY_TAG`	Docker image tag
`NETBIRD_RELAY_PORT`	Relay port (default: 33080)
`NETBIRD_RELAY_ENDPOINT`	Relay endpoint address
`NETBIRD_RELAY_AUTH_SECRET`	Authentication secret
`NETBIRD_RELAY_DOMAIN`	Relay server domain

Runtime Variables

Variable	Default	Description
`NB_LOG_LEVEL`	`info`	Log level
`NB_LISTEN_ADDRESS`	`:443`	Listen address
`NB_EXPOSED_ADDRESS`	-	Exposed address for peers
`NB_AUTH_SECRET`	-	Authentication secret
`NB_METRICS_PORT`	-	Prometheus metrics port
`NB_TLS_CERT_FILE`	-	TLS certificate file
`NB_TLS_KEY_FILE`	-	TLS key file
`NB_LETSENCRYPT_DATA_DIR`	-	Let's Encrypt data directory
`NB_LETSENCRYPT_DOMAINS`	-	Let's Encrypt domains
`NB_LETSENCRYPT_EMAIL`	-	Let's Encrypt email
`NB_HEALTH_LISTEN_ADDRESS`	-	Health check listen address
`NB_ENABLE_STUN`	`false`	Enable embedded STUN server
`NB_STUN_PORTS`	`3478`	STUN server UDP ports (comma-separated)
`NB_STUN_LOG_LEVEL`	`info`	STUN server log level

Dashboard Variables

Variable	Description
`NETBIRD_MGMT_API_ENDPOINT`	Management API endpoint URL
`NETBIRD_MGMT_GRPC_API_ENDPOINT`	Management gRPC endpoint
`LETSENCRYPT_DOMAIN`	Let's Encrypt domain (set to `none` if using own certs)
`LETSENCRYPT_EMAIL`	Let's Encrypt email

Dashboard authentication is automatically configured when using the embedded identity provider. The dashboard connects to the management server's built-in OAuth2 endpoints.

Coturn (TURN Server) Variables (Legacy)

The default quickstart deployment no longer uses a separate Coturn container. STUN functionality is now embedded in the relay service. The variables below are only relevant for legacy deployments or advanced configurations that still use Coturn.

Coturn configuration is generated from templates using these variables:

Variable	Default	Description
`TURN_DOMAIN`	-	TURN server domain
`TURN_USER`	-	TURN username
`TURN_PASSWORD`	-	TURN password
`TURN_MIN_PORT`	`49152`	Minimum relay port
`TURN_MAX_PORT`	`65535`	Maximum relay port
`TURN_EXTERNAL_IP_CONFIG`	-	External IP configuration

The Coturn service uses static ports: 3478 (STUN/TURN) and 5349 (TLS TURN).

Configuration Examples

Basic Setup

# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_LETSENCRYPT_EMAIL="admin@example.com"

PostgreSQL Database

# setup.env
NETBIRD_STORE_CONFIG_ENGINE="postgres"
NETBIRD_STORE_ENGINE_POSTGRES_DSN="postgres://user:password@localhost:5432/netbird?sslmode=disable"

Custom Ports (Behind Reverse Proxy)

# setup.env
NETBIRD_DOMAIN="netbird.example.com"
NETBIRD_DISABLE_LETSENCRYPT="true"
NETBIRD_MGMT_API_PORT="443"
NETBIRD_SIGNAL_PORT="443"

Disable Anonymous Metrics

# setup.env
NETBIRD_DISABLE_ANONYMOUS_METRICS="true"

Enable API Rate Limiting

Set these in your container environment or docker-compose:

environment:
  - NB_API_RATE_LIMITING_ENABLED=true
  - NB_API_RATE_LIMITING_RPM=60
  - NB_API_RATE_LIMITING_BURST=10

Variable Precedence

Configuration values are applied in the following order (later values override earlier):

Default values
Configuration file (config.yaml for combined setup, management.json for older multi-container setup)
Environment variables
Command-line flags