Tutoriales de VPS
NetBird en VPS (2026): WireGuard, Traefik HTTPS, políticas y copias
Aloje NetBird en Ubuntu con imágenes fijadas, Traefik HTTPS, clientes Linux, políticas de mínimo privilegio, Networks, DNS y copias verificadas.

Cuando una red WireGuard crece más allá de unos pocos equipos, mantener claves, rutas y permisos manualmente resulta difícil. NetBird combina el plano de datos WireGuard con registro, identidad, políticas y rutas privadas, útil para laboratorios, equipos pequeños y servidores multicloud.
Esta guía completa utiliza NetBird v0.78.1, publicado en septiembre de 2026, en Ubuntu 24.04. Incluye plano de control propio, Traefik HTTPS, clientes Linux y servidores desatendidos, acceso mínimo, Networks, DNS, copias y actualización. La versión es un ejemplo histórico; revise correcciones nuevas antes de desplegar hoy.
No todo el tráfico pasa por la VPS de control. Los peers con conexión directa intercambian WireGuard entre ellos; Relay interviene cuando esa conexión falla. Región y transferencia importan para el tráfico retransmitido, pero no equivalen automáticamente a la suma de todos los clientes.
| Opción | Control | Cliente | Identidad/políticas | Uso |
|---|---|---|---|---|
| WireGuard nativo | Configuración propia | WireGuard | Manual | Pocos equipos fijos |
| Tailscale | Proveedor | Tailscale | Gestionadas | Evitar mantener control |
| Headscale | Propio | Tailscale | Más configuración manual | Conservar ecosistema de clientes |
| NetBird | Puede alojarse | NetBird | Usuarios, grupos, políticas, Networks | Administración gráfica de varios usuarios/equipos |
Para servidores fijos, consulte WireGuard; para clientes Tailscale con coordinación propia, Headscale. NetBird reúne registro, identidad y permisos.
Instalar no crea automáticamente acceso mínimo. La política inicial Default permite All hacia All. Prepare y pruebe alternativas antes de quitarla.
Mínimo quickstart: 1 núcleo y 2 GB RAM. Un inicio práctico es 2 núcleos/2 GB/30 GB SSD para Docker, registros, actualizaciones y copias.
| Alcance | Recursos sugeridos | Observaciones |
|---|---|---|
| Personal, menos de 10 peers | 2 núcleos, 2 GB, 30 GB SSD | Control y poco Relay |
| Equipo, 10–50 peers | 2–4 núcleos, 4 GB, 50 GB SSD | Más usuarios, políticas y registros |
| Relay frecuente | 4 GB+ y vigilar transferencia | Banda VPS puede limitar |
| Alta disponibilidad | Diseñar redundancia | Una VPS sigue siendo punto único |
Puertos del original:
80/TCP: redirección HTTP; validación de certificado según método.443/TCP: Dashboard, API, Signal, relay y gRPC.3478/UDP: STUN para descubrir mapeo y negociar conexión directa.22/TCP: SSH limitado a administración.
El Traefik incluido usa TLS-ALPN-01 en 443, confirmado en el instalador fijado. El 80 público es opcional para redirección, no necesario para esa validación; debe estar libre en el host porque Traefik lo ocupa. Otros proxies pueden exigir 80 por HTTP-01. No copie puertos antiguos 33073, 10000 o 33080; netbird-server combinado utiliza entrada HTTPS y STUN.
Ejemplos:
- Dominio
netbird.example.com. - IPv4 documental
203.0.113.10. - Directorio
/opt/netbird.
Sustitúyalos. Configure DNS primero; con Cloudflare use DNS only al validar. Un proxy HTTP normal no reemplaza UDP/STUN ni rutas TLS/gRPC.
Compruebe desde su equipo:
dig +short A netbird.example.com
dig +short AAAA netbird.example.com
Instale dnsutils si falta dig en Linux. AAAA solo con IPv6 funcional. Revise VPS:
cat /etc/os-release
uname -m
free -h
df -h /
timedatectl status
sudo ss -lntup | grep -E ':(22|80|443|3478)\b' || true
No superponga con Nginx/Caddy/Traefik en 80/443. Existe modo proxy externo, pero exige HTTP/2, gRPC y conexiones largas correctos. Aquí usamos Traefik incluido.
Instale Docker, Compose v2, curl y 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"
Compruebe openssl y less. Cierre/reabra SSH para docker; pertenecer al grupo Docker equivale a root. Verifique:
docker version
docker compose version
docker run --rm hello-world
Use docker compose, no docker-compose antiguo.
Permita 443/TCP y 3478/UDP; 80/TCP si quiere redirección. SSH solo desde administración. Reglas originales con HTTP opcional:
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
Sustituya YOUR_ADMIN_IP. Conserve sesión y consola de rescate; consulte recuperación UFW. Docker administra reenvío: verifique publicaciones con ss, proveedor y prueba externa.
Descargar y revisar permite identificar el script antes de ejecutarlo. El checksum original coincide con el archivo de v0.78.1.
El instalador versionado usa imágenes latest por defecto. Antes del bloque original, establezca referencias explícitas. Dashboard v2.92.0 se publicó inmediatamente antes de NetBird v0.78.1; ambas etiquetas están en repositorios oficiales:
export NETBIRD_SERVER_IMAGE=netbirdio/netbird-server:0.78.1
export DASHBOARD_IMAGE=netbirdio/dashboard:v2.92.0
El instalador admite esas variables. Si usa una versión nueva, elija combinación compatible probada; los números de versión de servidor y Dashboard no coinciden necesariamente. Guarde identidades reales de imágenes.
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
Cambie el dominio: el instalador rechaza el documental literal. Seleccione [0] Traefik y dé correo ACME. Traefik gestiona certificados.
Para NetBird Proxy service elija N. Esa función opcional publica recursos privados; no es necesaria para control. Primero establezca acceso privado y luego evalúe DNS comodín, autenticación y exposición.
Archivos esperados:
/opt/netbird/
├── docker-compose.yml
├── config.yaml
├── dashboard.env
└── getting-started.sh
proxy.env aparece con proxy opcional. config.yaml y entornos contienen secretos. Proteja:
cd /opt/netbird
chmod 600 config.yaml dashboard.env
test ! -f proxy.env || chmod 600 proxy.env
docker compose config --quiet
docker compose ps
Proteja también Compose si lleva credenciales. docker compose config --quiet con salida cero solo valida sintaxis.
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 ocupa 80/443 y STUN 3478/UDP. Una respuesta normal a curl -I, como 200/302, prueba HTTPS básico, no registro ni políticas. Timeout: DNS, firewall o enlaces.
Busque servicios:
docker compose config --services
No suponga management, signal o coturn separados. Instalaciones combinadas usan netbird-server; despliegues antiguos se mantienen de otra forma.
Restrinja acceso inicial al administrador previsto. Abra:
https://netbird.example.com
/setup crea Owner con correo, nombre y contraseña fuerte solo si no hay usuarios. Después /setup redirige al login.
- Contraseña distinta de VPS, correo y demás sistemas.
- Cuenta normal diaria en Team; Owner para administrar.
- Administrador local probado antes de OIDC/SSO externo.
Descargue y revise en el equipo que se une:
curl -fsSLO https://pkgs.netbird.io/install.sh
less install.sh
sh ./install.sh
rm -f install.sh
Es un script separado que puede instalar la versión actual del repositorio. Compruebe versión y controle actualizaciones con una combinación probada contra su servidor. La etiqueta del instalador de control no fija clientes. Use directorio limpio antes de instalación privilegiada.
Inicio interactivo personal:
sudo netbird up --management-url https://netbird.example.com
netbird status
ip addr show wt0
Autentíquese y revise nombre, IP, SO y última conexión. Si no existe wt0, compruebe interfaz real.
Peers → Add Peer → Generate Key genera clave de un uso y 24 horas sin grupos automáticos por defecto. Evite literal en historial:
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
El valor puede aparecer brevemente en argumentos privilegiados; trátelo como secreto y elimine variable incluso tras error. En Settings → Setup Keys, configure claves reutilizables con vencimiento, usos y grupos. Peers Ephemeral se eliminan tras más de 10 minutos desconectados. Dispositivos de personas deben usar identidad, no clave larga compartida. Vencer/revocar una clave de registro no elimina automáticamente cada peer ya registrado; quite los no confiables.
Pruebe dos peers:
netbird status
netbird status --detail
ping -c 4 PEER_NETBIRD_IP
Normalmente Default permite All → All. Cree grupos mediante Access Control → Groups:
admins: portátiles/teléfonos de administración.servers: servidores administrados.workstations: equipos normales.routing-peers: nodos de reenvío.
Distinga grupos de identidad, peers y recursos. Aquí se etiquetan dispositivos para política peer-to-peer; un grupo IdP del mismo nombre no asigna automáticamente máquinas, especialmente las de Setup Key.
| Política | Source | Destination | Protocolo/puertos | Dirección |
|---|---|---|---|---|
| Admin SSH | admins | servers | TCP 22 | Una dirección |
| Admin Web | admins | servers | TCP 80,443 | Una dirección |
| Admin Ping | admins | servers | ICMP | Una dirección |
Asigne equipos, pruebe SSH/HTTPS/ping y una conexión prohibida; después elimine/desactive Default. Quitarla primero puede desconectar peers. Una regla amplia All → All sigue concediendo acceso aunque añada reglas estrechas. No hay DENY posterior que anule ALLOW anterior en este modelo.
Un Linux nativo 192.168.50.2 alcanza NAS 192.168.50.10 sin cliente. Habilite reenvío:
echo 'net.ipv4.ip_forward=1' \
| sudo tee /etc/sysctl.d/99-netbird-forward.conf
sudo sysctl --system
sysctl net.ipv4.ip_forward
En Dashboard:
Networksy crearHome LAN.- Resource
192.168.50.10/32. - Grupo
home-nas. - Routing Peer
192.168.50.2. - Source
adminsa Destinationhome-nassolo para puertos NAS necesarios.
Prefiera /32 en vez de 192.168.50.0/24 para no abrir cámaras, impresoras y router. Compruebe acceso local y retorno. Masquerade puede proporcionar retorno; sin él, la LAN necesita rutas adecuadas. Revise subredes superpuestas.
Use Networks para configuraciones nuevas. Network Routes está retirado para acceso ordinario; exit nodes siguen siendo caso Routes. Rutas antiguas sin ACL Groups pueden conceder acceso amplio.
Política Resource controla tráfico reenviado; SSH/web/DNS del routing peer en IP overlay necesita regla peer-to-peer con su grupo de destino. Su IP LAN puede necesitar además recurso/ruta que la cubra; distinga direcciones.
Nombres automáticos bastan en redes pequeñas. Para nas.home.internal configure DNS → Nameservers:
- DNS interno
192.168.50.53. - Match Domain
home.internal. - Distribución solo a grupos que lo necesitan.
- Recurso DNS alcanzable y UDP/TCP 53; si está en el router mismo, añada política peer.
Si otra VPN interfiere, desactive temporalmente DNS:
sudo netbird down
sudo netbird up \
--management-url https://netbird.example.com \
--disable-dns
DNS desactivado no elimina WireGuard tras reconectar, pero down/up interrumpe brevemente. Revise dominios, systemd-resolved y prioridad de VPN; reactive después del diagnóstico.
docker-compose.yml no basta. Usuarios, peers, políticas, claves y SQLite están en /var/lib/netbird/. Detenga netbird-server y preserve claves de cifrado y árbol completo.
Ejemplo original desde /opt/netbird:
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
El padre del archivo root puede impedir escribir al usuario; faltan reinicio fiable y sumas. Para Traefik incluido sin Proxy/CrowdSec, use la versión root revisada. Congele cambios, mantenga proyecto/overrides y copie configuración, datos y certificados privados:
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
El manifiesto verifica archivos relativos y el checksum externo queda junto al archivo. Compruebe salud al reiniciar. Si añade Proxy/CrowdSec, incluya proxy.env, reglas dinámicas, certificados, configuración y base CrowdSec. PostgreSQL/MySQL externo requiere respaldo propio; el directorio Docker no contiene todo. Restaurar certificados evita solicitudes concentradas de emisión.
Cifre y copie archivo/checksum fuera del host. En prueba aislada, compruebe archivo y sumas internas, seleccione imágenes/configuración/claves correspondientes y restaure en volumen real detenido. Incluya store.db cuando lo use esa versión. Evite dos controles de la misma identidad/dominio compitiendo por peers. Verifique usuarios, políticas, registros, alta controlada y comunicación.
Respalde y lea notas de servidor/Dashboard. Para netbird-server y dashboard:
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
Como están fijadas, edite referencias al destino revisado antes de pull. Si habilitó proxy opcional:
docker compose pull proxy
docker compose up -d --force-recreate proxy
docker compose exec proxy /go/bin/netbird-proxy --version
v0.78.1 del 4 de septiembre de 2026 corrige distribución Networks con routers basados en peers desde SQLite en v0.78.0. No conserve la versión afectada para este uso. Pruebe rutas, políticas y reconexión.
Migraciones pueden impedir volver a una imagen antigua. Revierta con copia previa de configuración/datos probada en aislamiento. Evite actualización automática no revisada mediante 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'
Revise A/AAAA, proxy, proveedor, puertos y Traefik. TLS-ALPN requiere 443 público; el requisito de validar por 80 solo aplica si cambia el método.
netbird status --detail
sudo systemctl status netbird --no-pager
sudo journalctl -u netbird -n 200 --no-pager
curl -I https://netbird.example.com
443 bloqueado impide configuración. STUN bloqueado aumenta Relay sin desconectar necesariamente todos. Revise hora para TLS y tokens.
Revise Access Control → Policies, pertenencia, protocolo y dirección. TCP 22 no permite ICMP; cree alternativas antes de quitar Default.
Revise router online, acceso LAN, forwarding, CIDR, política y retorno. Servicios propios necesitan política peer.
netbird status --detail muestra tipos. CGNAT, NAT simétrico y filtros UDP pueden impedir conexión directa. Compruebe STUN y recursos/geografía del relay; STUN correcto no garantiza enlace directo.
- A/AAAA alcanzables.
- 443/TCP, 3478/UDP y SSH restringido; 80 opcional para este Traefik.
docker compose config --quietcorrecto y servicios con imágenes revisadas.- HTTPS válido y
/setupcerrado después del alta inicial. - Identidad para personas y claves limitadas para servidores.
- Grupos y políticas específicos reemplazan Default.
- Networks y
/32donde corresponda. - Configuración y
/var/lib/netbird/copiados externamente y restaurados en prueba. - Notas revisadas y peers, políticas, Networks y DNS probados tras actualizar.
Es el mínimo quickstart para pocos peers. Mejor 2 núcleos/2 GB con margen; Relay frecuente exige transferencia y baja latencia.
No. Peers directos usan WireGuard entre ellos. Relay o exit node explícito transportan solo tráfico correspondiente.
Headscale para clientes Tailscale; NetBird para sus clientes, usuarios locales, políticas y Networks. Ambos exigen operar control, copias y actualización.
/setup es solo para almacén sin usuarios. No borre base para recuperar contraseña; use administrador existente o recuperación/PAT autorizado oficial.
Añada UDP 3478. Traefik valida en 443; 80 público es opcional para redirección pero debe estar libre localmente. Otros métodos pueden exigirlo. Sin STUN aumenta Relay.
No. Copie configuración/claves y estado detenido de netbird-server en /var/lib/netbird/, con componentes extra y bases externas. Pruebe restauración.