Advanced guide

NetBird is open-source and can be self-hosted on your servers.

It relies on components developed by NetBird Authors Management Service, Management UI Dashboard, Signal Service, a 3rd party open-source STUN/TURN service Coturn, and an identity provider (IDP).

If you would like to learn more about the architecture please refer to the architecture section.

If you are looking for a quick way of trying self-hosted NetBird, please refer to this guide. Otherwise, continue here to set up NetBird with custom IdPs.

Advanced self-hosting guide with a custom identity provider

Requirements

• Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
• Any Linux OS.
• Docker Compose installed (see Install Docker Compose).
• jq installed. In most distributions usually available in the official repositories and can be installed with sudo apt install jq or sudo yum install jq
• Domain name pointing to the public IP address of your server.
• Open TCP ports 80, 443, 33073, 10000, 33080 (Dashboard HTTP & HTTPS, Management gRPC & HTTP APIs, Signal gRPC API, Relay respectively) on your server.
• Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, UDP 3478, and range of ports, UDP 49152-65535, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
• Maybe a cup of coffee or tea :)

For this tutorial we will be using domain demo.netbird.io which points to our Ubuntu 22.04 machine hosted at Hetzner.

Step 1: Get the latest stable NetBird code

#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG

# this command will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO

Then switch to the infra folder that contains docker-compose file:

cd netbird/infrastructure_files/

Step 2: Prepare configuration files

To simplify the setup we have prepared a script to substitute required properties in the docker-compose.yml.tmpl and management.json.tmpl files.

The setup.env.example file contains multiple properties that have to be filled. You need to copy the example file to setup.env before updating it.

## example file, you can copy this file to setup.env and update its values
##
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
NETBIRD_AUTH_AUDIENCE=""
# e.g. netbird-client
NETBIRD_AUTH_CLIENT_ID=""
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""

• Set NETBIRD_DOMAIN to your domain, e.g. demo.netbird.io
• Configure NETBIRD_LETSENCRYPT_EMAIL property. This can be any email address. Let's Encrypt will create an account while generating a new certificate.

Step 3: Configure Identity Provider (IDP)

NetBird supports generic OpenID (OIDC) protocol allowing integration with any IDP following the specification.

NetBird's management service integrates with some of the most popular IDP APIs, allowing the service to cache and display user names and email addresses without storing sensitive data.

Pick the one that suits your needs, follow the steps, and continue with this guide:

Self-hosted options

• Continue with Zitadel.
• Continue with Keycloak.
• Continue with Authentik.

Managed options

• Continue with Azure AD.
• Continue with Google Workspace.
• Continue with Okta.
• Continue with Auth0.

Step 4: Disable single account mode (optional)

NetBird Management service runs in a single account mode by default since version v0.10.1. Management service was creating a separate account for each registered user before v0.10.1. Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network. In most cases, this is the desired behavior.

If you want to disable the single-account mode, set --disable-single-account-mode flag in the docker-compose.yml.tmpl command section of the management service.

Step 5: Run configuration script

Make sure all the required properties set in the setup.env file and run:

./configure.sh

This will export all the properties as environment variables and generate artifacts/docker-compose.yml, artifacts/management.json and artifacts/turnserver.conf files substituting required variables.

Step 6: Run docker compose:

cd artifacts
docker compose up -d

Step 7: Check docker logs (Optional)

cd artifacts
docker compose logs signal
docker compose logs management
docker compose logs coturn
docker compose logs dashboard

Advanced: Running NetBird behind an existing reverse-proxy

If you want to run NetBird behind your own reverse-proxy, some additional configuration-steps have to be taken to Step 2.

Configuration for NetBird

In setup.env:

• Set NETBIRD_DOMAIN to your domain, e.g. demo.netbird.io
• Set NETBIRD_DISABLE_LETSENCRYPT=true
• Add NETBIRD_MGMT_API_PORT to your reverse-proxy TLS-port (default: 443)
• Add NETBIRD_SIGNAL_PORT to your reverse-proxy TLS-port

Optional:

• Add TURN_MIN_PORT and TURN_MAX_PORT to configure the port-range used by the Turn-server

Now you can continue with Step 3.

Configuration for your reverse-proxy

Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.

The following endpoints have to be setup:

Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.

Advanced: Additional configurations for cloud providers

Hetzner

Hetzner uses stateless firewall, which means it doesn't "keep track of" whether or not an incoming packet belongs to an established connection. In this case, you may add to this server firewall an UDP port range equals to the result of:

sudo cat /proc/sys/net/ipv4/ip_local_port_range

More info can be found at this GitHub issue.

Oracle Cloud Infrastructure (OCI)

Linux images provided by Oracle Cloud includes some default firewall rules which block ingress UDP on port 3478. This is required by Coturn without which only peers in same LAN would be able to communicate with each other but not peers on different networks. Besides opening required ports on Security Rules, you also need to run below command on the virtual machine.

sudo iptables -I INPUT -p udp -m udp --dport 3478 -j ACCEPT

Backup

To backup your NetBird installation, you need to copy the configuration files, and the Management service databases.

The configuration files are located in the folder where you ran the installation script. To backup, copy the files to a backup location:

cd netbird/infrastructure_files/artifacts/
mkdir backup
cp docker-compose.yml turnserver.conf management.json backup/

To save the Management service databases, you need to stop the Management service and copy the files from the store directory using a docker compose command as follows:

docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management

Upgrade

To upgrade NetBird to the latest version, you need to review the release notes for any breaking changes and follow the upgrade steps below:

1. Run the backup steps described in the backup section.
2. Pull the latest NetBird docker images:

   cd netbird/infrastructure_files/artifacts/
   docker compose pull
   

   CopyCopied!
3. Restart the NetBird containers with the new images:

   docker compose up -d --force-recreate
   

   CopyCopied!

Get in touch

Feel free to ping us on Slack if you have any questions

• NetBird managed version: https://app.netbird.io
• Make sure to star us on GitHub
• Follow us on Twitter