VPS Tutorials
NetBird on a VPS (2026): WireGuard, Traefik HTTPS, policies and backups
Self-host NetBird on Ubuntu with pinned server and Dashboard images, Traefik HTTPS, Linux enrollment, least-privilege policies, Networks, DNS and verified backups.

Once a private WireGuard network grows beyond a few devices, maintaining keys, routes and permissions manually becomes difficult. NetBird combines the WireGuard data plane with device enrollment, user login, access policies and private-network routing, making it useful for labs, small teams and multicloud servers.
This full tutorial uses NetBird v0.78.1, released in September 2026, on an Ubuntu 24.04 VPS. It configures the self-hosted control plane with bundled Traefik HTTPS, Linux and unattended clients, minimum access policies, Networks, DNS, backups and upgrades. The pinned release is a historical deployment example; review newer security fixes before selecting a version today.
NetBird does not send every connection through the control VPS. Peers that establish a direct connection exchange WireGuard traffic with one another. Relay carries traffic when direct connectivity fails. Server region and transfer allowance matter for relayed traffic, but the sum of all client traffic is not automatically the VPS's bandwidth requirement.
| Option | Control plane | Client | Identity/policies | Suitable use |
|---|---|---|---|---|
| Native WireGuard | Your configuration | WireGuard | Manually maintained | Few fixed devices, simple topology |
| Tailscale | Vendor-hosted | Tailscale | Managed, established features | Avoid operating a control plane |
| Headscale | Self-hosted | Tailscale | More manual configuration | Keep the Tailscale client ecosystem |
| NetBird | Self-hosting available | NetBird | Users, groups, policies, Networks | Multiuser/device administration through a UI |
For a few fixed servers, see native WireGuard. For Tailscale clients with your own coordination service, see Headscale. NetBird suits integrated enrollment, identity and graphical access management.
Installation does not automatically establish minimum access. New accounts receive a Default policy allowing All to All. Build and test replacement policies, then remove the broad default.
The quickstart minimum is 1 CPU core and 2 GB RAM. A practical starting point is 2 cores/2 GB/30 GB SSD for Docker, logs, upgrades and backups.
| Scope | Suggested resources | Notes |
|---|---|---|
| Personal, fewer than 10 peers | 2 cores, 2 GB RAM, 30 GB SSD | Control plane and modest relay traffic |
| Team, 10–50 peers | 2–4 cores, 4 GB RAM, 50 GB SSD | More accounts, policies and logs |
| Frequent relaying | 4 GB+; monitor traffic allowance | VPS bandwidth can become limiting |
| High availability | Design redundancy, not only a larger host | One VPS remains a control-plane failure point |
The source lists these public ports:
80/TCP: HTTP redirects; certificate validation depends on the proxy's challenge method.443/TCP: Dashboard, management APIs, Signal, relay endpoints and gRPC.3478/UDP: STUN for mapping discovery and direct-connection negotiation.22/TCP: SSH restricted to administrator addresses.
For this bundled Traefik, certificates use TLS-ALPN-01 on 443, as confirmed by the pinned installer. Public port 80 is optional for redirects, not necessary for that validation. It must remain free on the host because Traefik binds it. Another proxy may require public 80 for HTTP-01. Do not copy older ports 33073, 10000 or 33080 into this deployment; the combined netbird-server uses the HTTPS entry and STUN.
The examples use:
- Domain
netbird.example.com. - Documentation IPv4
203.0.113.10. - Installation directory
/opt/netbird.
Replace them with your domain/address. Set DNS before installation. With Cloudflare DNS, use DNS only while validating deployment; ordinary HTTP proxying is not a substitute for reachable UDP/STUN and the required TLS/gRPC routes.
Check from your own computer:
dig +short A netbird.example.com
dig +short AAAA netbird.example.com
On Linux, install dnsutils if dig is absent. Keep AAAA only with working IPv6. Inspect the VPS:
cat /etc/os-release
uname -m
free -h
df -h /
timedatectl status
sudo ss -lntup | grep -E ':(22|80|443|3478)\b' || true
Do not install over an existing Nginx/Caddy/Traefik on 80/443. The external-proxy mode is available but must correctly support HTTP/2, gRPC and long-lived connections. This guide uses bundled Traefik.
Install Docker, Compose v2, curl and jq:
sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl jq docker.io docker-compose-v2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
Also ensure openssl and less are available for installer secrets and script review. Log out and back in for docker membership, understanding that Docker-group access is effectively root access. Check:
docker version
docker compose version
docker run --rm hello-world
Use docker compose, not the legacy docker-compose command.
Allow 443/TCP and 3478/UDP in the provider firewall; allow 80/TCP if retaining HTTP redirects. Restrict SSH to your management IP. The source's rules, including optional HTTP access, are:
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from YOUR_ADMIN_IP to any port 22 proto tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw enable
sudo ufw status numbered
Replace YOUR_ADMIN_IP before enabling UFW. Keep the current SSH connection and provider recovery console available; see the UFW recovery checklist. Docker controls forwarding rules itself, so verify publications with ss, provider rules and an external connectivity test.
The official script can be piped directly to Bash, but downloading and verifying it first makes its identity reviewable. The source checksum matches the v0.78.1 release asset.
The versioned installer still defaults to latest server/dashboard images. Before running the source installation block, set explicit image references. Dashboard v2.92.0 was published immediately before NetBird v0.78.1; both tags are available in their official repositories:
export NETBIRD_SERVER_IMAGE=netbirdio/netbird-server:0.78.1
export DASHBOARD_IMAGE=netbirdio/dashboard:v2.92.0
These variables are recognized by the reviewed installer. For a newer deployment, choose and test the appropriate server/dashboard combination rather than assuming their version numbers match. Preserve exact running image identities in backups.
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/netbird
cd /opt/netbird
curl -fL \
https://github.com/netbirdio/netbird/releases/download/v0.78.1/getting-started.sh \
-o getting-started.sh
echo 'a8d17cdb2229c680514063a6893d117aad55343d8dd2c703d1aa1033577b1570 getting-started.sh' \
| sha256sum -c -
chmod 700 getting-started.sh
export NETBIRD_DOMAIN=netbird.example.com
bash ./getting-started.sh
Replace the example hostname; the installer rejects the literal documentation domain. Select [0] Traefik when asked for proxy type, and supply the ACME contact email. Traefik manages certificates.
Choose N for NetBird Proxy service. That optional feature publishes selected private resources; it is not needed for the control plane. First establish private access, then separately review wildcard DNS, authentication and exposure if enabling it later.
Expect these files:
/opt/netbird/
├── docker-compose.yml
├── config.yaml
├── dashboard.env
└── getting-started.sh
proxy.env appears when the optional proxy is enabled. config.yaml and environment files contain sensitive configuration. Restrict access:
cd /opt/netbird
chmod 600 config.yaml dashboard.env
test ! -f proxy.env || chmod 600 proxy.env
docker compose config --quiet
docker compose ps
Also protect Compose if it embeds credentials. docker compose config --quiet with exit zero checks parsing, not runtime behavior.
cd /opt/netbird
docker compose ps
docker compose logs --tail=100 netbird-server dashboard
curl -I https://netbird.example.com
sudo ss -lntup | grep -E ':(80|443|3478)\b'
Traefik owns 80/443, and STUN uses 3478/UDP. A normal response to curl -I, including 200 or 302, establishes basic HTTPS reachability, not successful enrollment or policy enforcement. Timeouts suggest DNS, firewall or binding problems.
Find service names with:
docker compose config --services
Do not assume separate management, signal or coturn containers. New combined deployments use netbird-server; older installation guides require different maintenance steps.
Restrict initial dashboard access to the intended administrator until bootstrap is complete. Visit:
https://netbird.example.com
The initial /setup page creates the first owner using email, name and a strong password. It opens only when no users exist. Afterward /setup redirects to ordinary login.
- Use an owner password distinct from VPS, email and other systems.
- Create an ordinary daily account through Team; reserve Owner for administration.
- Keep a tested local administrator before enabling external OIDC/SSO.
Download and inspect the client installer on the machine joining the network:
curl -fsSLO https://pkgs.netbird.io/install.sh
less install.sh
sh ./install.sh
rm -f install.sh
The client script is separate and may install the repository's current package. Check its version and control package updates to a combination tested with your management server; the installer asset's tag does not pin a client. Review it in a clean directory before privileged installation.
For a personal device, use interactive login:
sudo netbird up --management-url https://netbird.example.com
netbird status
ip addr show wt0
Authenticate through your self-hosted login page, then check peer name, NetBird address, OS and last-seen time in the dashboard. Interface names can vary; inspect actual interfaces if wt0 is absent.
For unattended servers, Peers → Add Peer → Generate Key generates a one-off key with a 24-hour lifetime and no automatic groups by default. Avoid a literal key in history:
read -rsp 'NetBird setup key: ' NETBIRD_SETUP_KEY
echo
sudo netbird up \
--management-url https://netbird.example.com \
--setup-key "$NETBIRD_SETUP_KEY"
unset NETBIRD_SETUP_KEY
netbird status
The variable avoids recording its value in the typed command, but the key can briefly appear in privileged process arguments. Treat it as a secret and unset it even after a failed attempt. At Settings → Setup Keys, configure reusable keys with expiration, usage limits and automatic peer groups. Ephemeral peers are removed after more than 10 minutes offline. Use identity login for user devices instead of sharing a long-lived machine key. Revocation/expiry of an enrollment key does not automatically revoke every peer it already enrolled; remove untrusted peers explicitly.
Enroll two peers and test:
netbird status
netbird status --detail
ping -c 4 PEER_NETBIRD_IP
Initial communication often succeeds because Default permits All → All. Establish groups through Access Control → Groups:
adminsfor administrator laptops/phones.serversfor servers under administration.workstationsfor ordinary devices.routing-peersfor forwarding nodes.
Distinguish user identity groups, peer groups and resource groups. This example labels peers for peer-to-peer access; do not assume an identically named IdP group automatically assigns every machine, particularly setup-key peers.
Create alternatives:
| Policy | Source | Destination | Protocol/ports | Direction |
|---|---|---|---|---|
| Admin SSH | admins | servers | TCP 22 | One-way |
| Admin Web | admins | servers | TCP 80,443 | One-way |
| Admin Ping | admins | servers | ICMP | One-way |
Assign the test devices, verify SSH/HTTPS/ping and also a prohibited connection, then disable/delete Default. Removing it first can disconnect peers. Policies grant access; a broad All → All remains effective even after adding narrower rules. There is no later DENY rule overriding an earlier ALLOW in this model.
Suppose a native Linux router peer 192.168.50.2 can reach NAS 192.168.50.10, which cannot run a client. Enable forwarding on the router:
echo 'net.ipv4.ip_forward=1' \
| sudo tee /etc/sysctl.d/99-netbird-forward.conf
sudo sysctl --system
sysctl net.ipv4.ip_forward
In the dashboard:
- Open
Networksand createHome LAN. - Add Resource
192.168.50.10/32. - Assign resource group
home-nas. - Choose
192.168.50.2as Routing Peer. - Allow Source
adminsto Destinationhome-nasonly on required NAS ports.
Prefer /32 over exposing 192.168.50.0/24: do not accidentally include cameras, printers or router administration. Verify the routing peer can reach the backend and that return traffic works. Masquerading can provide the return path; without it, the LAN needs appropriate return routes. Check overlapping home/office subnets before distribution.
Prefer Networks for new remote-access configurations. Legacy Network Routes are deprecated for ordinary resource access; exit-node use remains a Routes case. A legacy route without ACL Groups can grant unintended access.
Resource policy controls forwarded traffic. Access to the routing peer's own SSH/web/DNS at its overlay address needs a separate peer-to-peer policy with the router group as destination. Its LAN address may additionally require a covering resource/route; do not confuse the two addresses.
Automatic peer names are simplest for small networks. For nas.home.internal or enterprise domains, configure DNS → Nameservers:
- Internal DNS such as
192.168.50.53. - Match Domain
home.internal. - Distribution only to groups needing that DNS.
- A reachable DNS resource and UDP/TCP 53 policies; if DNS runs on the routing peer itself, add its peer policy too.
When another VPN conflicts, temporarily disable NetBird DNS management:
sudo netbird down
sudo netbird up \
--management-url https://netbird.example.com \
--disable-dns
Disabling DNS leaves the WireGuard network in use after reconnection; the down/up sequence briefly interrupts it. If this resolves the conflict, inspect match domains, systemd-resolved and VPN DNS priorities. Re-enable normal DNS after diagnosis rather than permanently relying on IPs.
docker-compose.yml alone is insufficient. Users, peers, policies, keys and default SQLite state live under /var/lib/netbird/. Stop netbird-server before copying. Preserve datastore/session encryption keys and complete data, not merely one database filename.
The source example from /opt/netbird is:
cd /opt/netbird
BACKUP_DATE="$(date -u +%Y%m%dT%H%M%SZ)"
BACKUP_DIR="/var/backups/netbird/$BACKUP_DATE"
sudo install -d -m 0700 -o "$USER" -g "$USER" "$BACKUP_DIR"
cp docker-compose.yml config.yaml dashboard.env "$BACKUP_DIR/"
test ! -f proxy.env || cp proxy.env "$BACKUP_DIR/"
docker compose stop netbird-server
docker compose cp -a netbird-server:/var/lib/netbird/ "$BACKUP_DIR/"
docker compose start netbird-server
tar -C /var/backups/netbird \
-czf "/var/backups/netbird/netbird-$BACKUP_DATE.tar.gz" \
"$BACKUP_DATE"
tar -tzf "/var/backups/netbird/netbird-$BACKUP_DATE.tar.gz" | head
docker compose ps
Its root-owned archive parent can prevent the non-root tar command from writing, and it lacks reliable restart handling and checksum verification. For this bundled-Traefik topology with optional Proxy/CrowdSec disabled, use the reviewed root-run version. Freeze administrative changes, keep the same deployment project/overrides, and save configuration, all server data and Traefik certificate state privately:
sudo bash <<'BACKUP'
set -Eeuo pipefail
umask 077
cd /opt/netbird
compose=(docker compose -f docker-compose.yml)
mapfile -t running_services < <("${compose[@]}" ps --status running --services)
test "${#running_services[@]}" -gt 0
mapfile -t container_ids < <("${compose[@]}" ps -a -q)
test "${#container_ids[@]}" -gt 0
install -d -m 0700 /var/backups/netbird
backup_dir=$(mktemp -d "/var/backups/netbird/$(date -u +%Y%m%dT%H%M%SZ)-XXXXXX")
docker inspect --format '{{.Name}} {{.Config.Image}} {{.Image}}' "${container_ids[@]}" > "$backup_dir/images.txt"
docker inspect --format '{{.Name}} {{json .Mounts}}' "${container_ids[@]}" > "$backup_dir/mounts.txt"
resume_stack() { "${compose[@]}" start "${running_services[@]}" >/dev/null || true; }
trap resume_stack EXIT
"${compose[@]}" stop
cp -p docker-compose.yml config.yaml dashboard.env getting-started.sh "$backup_dir/"
for file in .env proxy.env traefik-dynamic.yaml; do
if test -f "$file"; then cp -p "$file" "$backup_dir/"; fi
done
"${compose[@]}" cp -a netbird-server:/var/lib/netbird/ "$backup_dir/"
"${compose[@]}" cp -a traefik:/letsencrypt/ "$backup_dir/traefik_letsencrypt/"
(cd "$backup_dir" && find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS && sha256sum -c SHA256SUMS)
archive="$backup_dir.tar.gz"
tar -C /var/backups/netbird -czf "$archive" "$(basename "$backup_dir")"
tar -tzf "$archive" >/dev/null
(cd /var/backups/netbird && sha256sum "$(basename "$archive")" > "$(basename "$archive").sha256")
printf 'Backup archive: %s\n' "$archive"
BACKUP
The manifest verifies relative files; the outer archive checksum is beside it. Check service health after the restart attempt. If Proxy/CrowdSec is later enabled, include proxy.env, dynamic routing, proxy certificates, CrowdSec configuration and its database as described in the official guide. External PostgreSQL/MySQL stores need a separate consistent database backup; the Docker data directory then does not contain the whole store. Traefik certificates can be reissued, but restoring them reduces issuance bursts.
Encrypt and copy the archive plus checksum offsite. For a drill, verify the archive, extract in isolation, verify internal checksums, use the matching images/configuration/keys, and restore data into the destination's actual stopped volume. Ensure the complete data tree, including store.db when used by that version, is present. Isolate the restored control plane from production peer discovery/enrollment until validation; do not let two copies of the same domain/identity compete. Confirm users, policies and peer records can be read, then test controlled enrollment and communication.
Back up first and review server/dashboard release notes. For combined netbird-server and dashboard, the source commands are:
cd /opt/netbird
docker compose pull netbird-server dashboard
docker compose up -d --force-recreate netbird-server dashboard
docker compose ps
docker compose logs --tail=100 netbird-server dashboard
Because images are pinned here, edit the reviewed target references before pulling; pull alone does not choose a new version. If the optional proxy was enabled, update it separately:
docker compose pull proxy
docker compose up -d --force-recreate proxy
docker compose exec proxy /go/bin/netbird-proxy --version
The v0.78.1 release on September 4, 2026 fixes distribution of networks with peer-based routers from SQLite in v0.78.0. Do not remain on that affected version for these Networks deployments. Verify routing, policies and reconnection after upgrading.
Database migrations may make an old image incompatible. Plan rollback around the pre-upgrade configuration/data set and test it in isolation. Avoid unreviewed automatic control-plane updates through tools such as Watchtower.
dig +short A netbird.example.com
dig +short AAAA netbird.example.com
sudo ss -lntp | grep -E ':(80|443)\b'
docker compose config --services
docker compose logs --tail=200 | grep -iE 'acme|certificate|error'
Check A/AAAA, proxying, provider rules, occupied ports and Traefik logs. For this TLS-ALPN configuration, public 443 challenge reachability is essential; port 80 validation applies only if the challenge method changes.
netbird status --detail
sudo systemctl status netbird --no-pager
sudo journalctl -u netbird -n 200 --no-pager
curl -I https://netbird.example.com
Blocked control-plane 443 prevents obtaining configuration. Blocked STUN 3478 can increase relaying without making every peer offline. Check clocks because TLS and login tokens depend on time.
Inspect Access Control → Policies, source/destination membership, protocol and direction. TCP 22 permission does not allow ICMP. Verify alternatives existed before removing Default.
Check router availability, LAN reachability, IPv4 forwarding, resource CIDR, source/resource policy and return paths. Router-local services need a peer-to-peer rule as well.
Inspect types with netbird status --detail. CGNAT, symmetric NAT, corporate restrictions and strict UDP firewalls can prevent direct paths. Check STUN reachability and choose suitable relay geography/traffic capacity; successful STUN alone does not guarantee direct connections.
- A/AAAA point only to reachable addresses.
- 443/TCP, 3478/UDP and restricted SSH are allowed; public 80 is optional for this Traefik's redirects.
docker compose config --quietpasses and services run using the reviewed image references.- HTTPS is valid and
/setupis closed after bootstrap. - User devices use identity login; servers use limited-lifetime setup keys.
- Specific groups/policies replace the broad Default.
- New resource access uses Networks and
/32where appropriate. - Configuration and
/var/lib/netbird/are backed up offsite and restoration is tested. - Release notes are reviewed; peers, policies, Networks and DNS are retested after upgrades.
That is the quickstart minimum for few peers. Prefer 2 cores/2 GB for headroom; frequent relaying makes transfer allowance and latency especially important.
No. Direct peers exchange WireGuard traffic. Relayed connections or a deliberately configured exit node carry the relevant traffic through those nodes.
Headscale fits existing Tailscale clients. NetBird offers its clients, local users, groups/policies and Networks. Both require your own control-plane operation, backups and upgrades.
/setup is only for an empty user store, then redirects to login. Do not delete the database to recover a password; use an existing administrator or the official authorized PAT/recovery procedure.
Include UDP 3478 for STUN. Bundled Traefik validates certificates on 443; public 80 is optional for redirects, although it must be free locally. Other proxy challenge methods may require public 80. Blocking STUN often increases relay latency/traffic.
No. Save configuration/encryption keys and the state of netbird-server under /var/lib/netbird/ while stopped, together with any extra components and external databases. Test a restore.