import {Note} from "@/components/mdx";

# 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.

<Note>
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.
</Note>

## Overview

NetBird uses two types of environment variables:

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

## Installation Script Variables

These are read from the shell environment by the install and migration scripts (`getting-started.sh`, `getting-started-enterprise.sh`, `migrate.sh`), not from `setup.env`. Pass them on the command line when you run the script.

| Variable | Default | Description |
|----------|---------|-------------|
| `NETBIRD_DOCKER_SUBNET` | `172.30.0.0/24` | The `/24` used for the generated Docker bridge network. The gateway (`.1`) and Traefik's static address (`.10`) are derived from it, along with the trusted-proxy pins in the generated server configuration. |

```bash
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | NETBIRD_DOCKER_SUBNET=10.123.45.0/24 bash
```

The value must be a `/24` ending in `.0`. `0.0.0.0/8`, `127.0.0.0/8`, `169.254.0.0/16`, `224.0.0.0` and above, and `100.64.0.0/10` are rejected — the last because NetBird assigns overlay peer addresses from that range, so a Docker bridge there would shadow your NetBird network.

Before writing any files, the scripts check the existing Docker networks and stop with an actionable error if one overlaps the chosen subnet, instead of failing later during `docker compose up`. Existing networks are never modified. Host routes such as LANs and VPN tunnels are not inspected — use this variable if the default range collides with one of those.

<Note>
If a run stops on a network conflict, see [Script exits with a Docker network conflict](/selfhosted/troubleshooting/installation#script-exits-with-a-docker-network-conflict).
</Note>

## 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

<Note>
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`.
</Note>

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

<Note>
See [Management Postgres Store](/selfhosted/maintenance/postgres-store) for PostgreSQL setup details.
</Note>

### Single Account Mode

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

<Note>
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.
</Note>

### 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 |
| `NB_SETUP_PAT_ENABLED` | Enable optional Personal Access Token creation from `/api/setup` during initial setup. See [Automated Setup](/selfhosted/automated-setup). |

### Advanced Runtime Variables

| Variable | Description |
|----------|-------------|
| `NB_PPROF_ADDR` | Start the unauthenticated Go pprof HTTP listener at a `host:port` address, for example `127.0.0.1:6060`. Unset disables it. Bind to loopback or another trusted interface and restart the server after changing it; never expose pprof directly to the public internet. |
| `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_TRUSTED_PROXIES` | - | Comma-separated IP addresses or CIDRs for immediate upstream proxies whose `X-Real-Ip` and `X-Real-Port` headers the relay may trust. Empty trusts no forwarding headers. |
| `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 |

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

## Coturn (TURN Server) Variables (Legacy)

<Note>
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.
</Note>

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

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

### PostgreSQL Database

```bash
# 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)

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

### Disable Anonymous Metrics

```bash
# setup.env
NETBIRD_DISABLE_ANONYMOUS_METRICS="true"
```

### Enable API Rate Limiting

Set these in your container environment or docker-compose:

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

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

## See Also

- [Self-hosting Quickstart Guide](/selfhosted/selfhosted-quickstart)
- [Advanced Self-hosting Guide](/selfhosted/selfhosted-guide)
- [Configuration Files Reference](/selfhosted/maintenance/configuration-files) - Detailed documentation for docker-compose.yml, config.yaml, and other config files
- [Management SQLite Store](/selfhosted/maintenance/sqlite-store)
- [Management Postgres Store](/selfhosted/maintenance/postgres-store)
