Back Up and Restore Your Self-Hosted NetBird Installation
Updated
A NetBird server that loses its data directory loses every account, peer, policy and setup key, and every client has to re-enroll. This page shows what to copy so that a fresh server can pick up exactly where the old one left off, and how to put that copy back.
A self-hosted installation lives in three places:
- Configuration files in the directory where you ran the installation script. They describe the deployment.
- Docker volumes that hold state: the Management database and keys, and the CrowdSec database if you enabled it. This is the part you cannot regenerate.
- Certificates in Docker volumes. Traefik and the proxy reissue these on their own, so backing them up is optional.
The steps below use backup/ as the target directory and assume the default quickstart layout with the built-in Traefik reverse proxy. If your deployment predates the combined netbird-server container, jump to Older Setup.
What to back up
| Item | Where | Present when | Why it matters |
|---|---|---|---|
docker-compose.yml, config.yaml, dashboard.env | Install directory | Always | Service definitions and server configuration. See the Configuration Files Reference. |
proxy.env, traefik-dynamic.yaml | Install directory | Reverse proxy enabled | Proxy access token and the Traefik routing rules that pass TLS through to the proxy. |
crowdsec/ directory | Install directory | CrowdSec enabled | CrowdSec configuration, mounted into the container at /etc/crowdsec. |
nginx-netbird.conf, caddyfile-netbird.txt, npm-advanced-config.txt | Install directory | External reverse proxy chosen during setup | Snippets for your own reverse proxy. Harmless to copy if present. |
/var/lib/netbird in netbird-server | Docker volume netbird_data | Always | Management database (SQLite by default), encryption keys and state. Required. |
/var/lib/crowdsec/data in crowdsec | Docker volume crowdsec_db | CrowdSec enabled | CrowdSec LAPI database, including the bouncer key that proxy.env references. Without it the restored proxy cannot authenticate to CrowdSec. |
/certs in proxy | Docker volume netbird_proxy_certs | Reverse proxy enabled | Certificates for proxied services. Optional: the proxy reissues them, but restoring avoids a burst of Let's Encrypt requests. |
/letsencrypt in traefik | Docker volume netbird_traefik_letsencrypt | Built-in Traefik | Certificates for the NetBird domain itself. Optional, same reasoning as above. |
If you moved the Management database to PostgreSQL or MySQL, the netbird_data volume no longer holds it. Back up the database server with its own tools as well. See PostgreSQL store.
Create a backup
Run these commands from the install directory.
1. Stop the services
Stopping the containers guarantees a consistent copy of the databases. Stopping only netbird-server is enough if you do not run CrowdSec; stopping everything is simplest.
docker compose stop
2. Copy the configuration files
mkdir -p backup
cp docker-compose.yml config.yaml dashboard.env backup/
If the reverse proxy is enabled, also copy its files:
cp proxy.env traefik-dynamic.yaml backup/
If CrowdSec is enabled, copy its configuration directory:
cp -r crowdsec backup/crowdsec
3. Copy the data volumes
docker compose cp reads from a stopped container, so the services do not need to be running.
docker compose cp -a netbird-server:/var/lib/netbird/ backup/
This creates backup/netbird/. If CrowdSec is enabled, copy its database too:
docker compose cp -a crowdsec:/var/lib/crowdsec/data/ backup/crowdsec_db/
4. Optional: copy the certificates
Skip this step if you are happy to let Traefik and the proxy request new certificates on the restored server.
docker compose cp -a proxy:/certs/ backup/proxy_certs/
docker compose cp -a traefik:/letsencrypt/ backup/traefik_letsencrypt/
5. Start the services and archive the backup
docker compose start
tar czf netbird-backup.tar.gz -C backup .
Move netbird-backup.tar.gz off the server. It contains the encryption keys for your Management database and every secret in the configuration files, so treat it like a private key.
Restore on a new server
The restored server must be reachable under the same domain as the old one. Peers, the dashboard and the relay are all configured with that domain, so once DNS points at the new IP address, clients reconnect without re-enrolling.
Before you start:
- Install Docker and Docker Compose.
- Open the same ports as on the old server: TCP 80 and 443, UDP 3478 for STUN, and UDP 51820 if the reverse proxy is enabled.
- Copy
netbird-backup.tar.gzto the new server.
1. Unpack the backup and restore the configuration files
mkdir -p netbird backup
tar xzf netbird-backup.tar.gz -C backup
cd netbird
cp ../backup/docker-compose.yml ../backup/config.yaml ../backup/dashboard.env .
If the reverse proxy is part of the backup, also restore its files:
cp ../backup/proxy.env ../backup/traefik-dynamic.yaml .
If CrowdSec is part of the backup, also restore its configuration directory:
cp -r ../backup/crowdsec .
2. Create the containers without starting them
Creating the containers also creates their empty volumes, which you fill in the next step.
docker compose create netbird-server
If CrowdSec is part of the backup, create it too:
docker compose create crowdsec
3. Restore the data volumes
docker compose cp -a ../backup/netbird/. netbird-server:/var/lib/netbird/
If CrowdSec is part of the backup, restore its database too:
docker compose cp -a ../backup/crowdsec_db/. crowdsec:/var/lib/crowdsec/data/
4. Optional: restore the certificates
Only if you copied them in the backup:
docker compose create proxy traefik
docker compose cp -a ../backup/proxy_certs/. proxy:/certs/
docker compose cp -a ../backup/traefik_letsencrypt/. traefik:/letsencrypt/
5. Start everything
docker compose up -d
Open the dashboard under your domain and check that your peers, policies and setup keys are there. Peers show as connected once DNS has propagated and they reach the new server.
Older Setup (Separate Containers)
If your deployment uses the older setup with separate containers (management, signal, relay, coturn), back up the configuration files:
mkdir backup
cp docker-compose.yml Caddyfile dashboard.env management.json relay.env backup/
To save the Management service database:
docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management
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 X