NetBird en tu propio servidor: mesh VPN como Tailscale sin nube

Qué configuramos y para qué

NetBird es una plataforma self-hosted para crear una mesh-VPN. Por su finalidad, es similar a Tailscale, ZeroTier y Headscale: instalas el agente en servidores, portátiles y otros dispositivos, los autorizas en una misma red y obtienes conectividad protegida entre los participantes.

WireGuard constituye la base de la transmisión de datos. Esto significa que el tráfico de usuario, siempre que sea posible, circula directamente entre dos nodos. El servidor central de NetBird no tiene que actuar como proxy para cada paquete: almacena el estado de la red, entrega configuraciones a los nodos peer, aplica políticas ACL, ayuda a detectar participantes y proporciona un panel administrativo.

Si no es posible una conexión directa debido a CGNAT, NAT simétrico o un firewall corporativo, NetBird puede transmitir el tráfico mediante un relay TURN. En un esquema self-hosted, este relay suele ser coturn, ejecutado en el mismo VPS. Esto no elimina el cifrado de WireGuard: TURN ve el flujo de transporte, pero no descifra el tráfico VPN.

Qué obtendrás al seguir la guía

Como resultado, tendrás un dominio como netbird.example.com con un panel de gestión HTTPS. En el panel podrás invitar usuarios, crear setup keys para servidores sin inicio de sesión interactivo, agrupar peers, añadir rutas a subredes locales y restringir el acceso mediante reglas.

Cada dispositivo conectado recibirá una dirección de la red interna de NetBird, por ejemplo 100.64.0.0/10 o el rango que elijas. Podrás conectarte a servicios privados mediante SSH, abrir bases de datos internas, vincular varios VPS, dar a los desarrolladores acceso únicamente a la infraestructura de staging o publicar una red doméstica sin redirigir puertos en cada dispositivo.

Por qué no usar simplemente WireGuard

WireGuard convencional es excelente para esquemas de «cliente — servidor», pero empieza a requerir administración manual con decenas de nodos. Hay que crear claves, añadir bloques peer a la configuración de todas las máquinas, coordinar AllowedIPs, actualizar archivos al revocar un dispositivo y resolver problemas de NAT.

NetBird automatiza este trabajo. El administrador gestiona objetos lógicos: usuarios, grupos, rutas y políticas. El agente recibe por sí mismo la configuración actualizada. Al eliminar un portátil de la red, su clave deja de recibir una configuración funcional, y al añadir un servidor nuevo no es necesario editar manualmente la configuración de todos los nodos existentes.

Cloud-managed y self-hosted: cuál elegir

NetBird self-hosted tiene sentido cuando son importantes la independencia de una cuenta externa, el control sobre los metadatos de red, una política propia de retención de datos o la integración con SSO corporativo. Para un equipo de varias personas, también es una buena forma de estudiar una arquitectura mesh-VPN moderna sin mantener manualmente decenas de configuraciones de WireGuard.

NetBird no hace que el VPS sea invisible para Internet automáticamente. Los servicios públicos siguen necesitando protección mediante firewall, actualizaciones, contraseñas sólidas y ACL independientes. La mesh-VPN debe considerarse una capa de conectividad protegida, no un sustituto de la seguridad básica del servidor.

Qué configuración de VPS se necesita para esta tarea

La carga de NetBird depende no tanto del número de peers registrados como de la cantidad de conexiones de relay activas a través de TURN. Si los dispositivos se conectan directamente, el VPS atiende principalmente el panel web, la API, PostgreSQL y la señalización. Si muchos clientes trabajan constantemente detrás de un NAT complejo, coturn puede consumir una cantidad considerable de tráfico y CPU.

Para la mayoría de infraestructuras personales y equipos pequeños, una opción inicial práctica es 2 vCPU, 4 GB de RAM, 50 GB NVMe, IPv4 dedicado y puerto de 1 Gbit/s. Por ejemplo, puedes elegir un VPS con las características indicadas, instalar Ubuntu Server 24.04 LTS y dejar margen de memoria para PostgreSQL, Docker y la futura monitorización.

Por qué se necesita un IPv4 público

Un IPv4 público simplifica el funcionamiento de TURN y el acceso al panel de management. IPv6 es útil, pero no reemplaza IPv4: algunos proveedores móviles y domésticos aún funcionan mediante IPv4 NAT, y ciertos clientes pueden no tener conectividad IPv6 completa. Idealmente, el servidor debería contar con ambas direcciones.

Comprueba si el proveedor permite tráfico UDP entrante. Para que NetBird funcione normalmente, se requieren los puertos UDP de WireGuard y TURN. Si UDP se filtra a nivel de la plataforma, algunos clientes se conectarán de forma inestable o no podrán utilizar relay en absoluto.

Cuándo se necesita un dedicated en vez de un VPS

Un servidor dedicated se justifica no por el control plane en sí, sino por la carga de red y los requisitos de aislamiento. Es útil si TURN transmite regularmente cientos de megabits por segundo, la red se utiliza como gateway para un gran número de empleados, se requiere rendimiento de CPU garantizado o la política de seguridad prohíbe la virtualización compartida.

Para 5–100 peers, normalmente no se necesita un dedicated. Es mucho más eficiente empezar con un VPS, activar la monitorización de carga y mover coturn por separado a un segundo VPS si el tráfico de relay se convierte en un cuello de botella. Esta separación es más fácil de escalar y mantener que una migración prematura a un servidor grande.

Cómo elegir la ubicación

La ubicación afecta principalmente a la latencia hacia el control plane y el relay TURN. Las conexiones directas de WireGuard entre peers no tienen por qué pasar por el VPS, por lo que dos clientes de la misma ciudad intercambiarán datos con baja latencia independientemente del país donde se encuentre el control plane. Sin embargo, en una conexión mediante relay, todo el tráfico pasará por TURN.

Ubica el VPS cerca de la mayoría de usuarios o de las redes críticas. Si el equipo está distribuido entre Europa y Asia, elige un punto neutral para el panel y, si es necesario, añade un segundo relay TURN en otra región. Para acceder a un servidor doméstico, elige una ubicación con una buena ruta hacia el ISP doméstico, no solo el precio más bajo.

Preparación del servidor

La guía está diseñada para un servidor limpio con Ubuntu Server 24.04 LTS x86_64. Esta versión cuenta con soporte a largo plazo, un kernel moderno y paquetes Docker estables. Antes de comenzar, cree un registro DNS de tipo A: netbird.example.com debe apuntar a la IPv4 pública del VPS. Si utiliza IPv6, agregue también un registro AAAA.

No instale NetBird directamente como root. Cree un administrador independiente, agregue una clave SSH y desactive el inicio de sesión con contraseña solo después de verificarlo. Mantenga abierta la sesión actual de root hasta asegurarse de que el inicio de sesión con el nuevo usuario funciona.

Actualización del sistema operativo

Conéctese al servidor mediante SSH e instale las actualizaciones disponibles. El comando actualiza el índice de paquetes, aplica parches de seguridad y reinicia el servidor solo si es necesario.

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Después de reiniciar, vuelva a conectarse y compruebe la versión del sistema.

cat /etc/os-release
uname -r

Creación de usuario y configuración de SSH

Sustituya vpnadmin por su propio nombre de usuario. En el equipo de trabajo, cree previamente una clave con el comando ssh-keygen -t ed25519, si aún no dispone de una.

sudo adduser vpnadmin
sudo usermod -aG sudo vpnadmin
sudo install -d -m 700 -o vpnadmin -g vpnadmin /home/vpnadmin/.ssh

Copie la clave pública en el archivo authorized_keys. Inserte una línea que comience por ssh-ed25519 en lugar del ejemplo.

sudo nano /home/vpnadmin/.ssh/authorized_keys
sudo chown vpnadmin:vpnadmin /home/vpnadmin/.ssh/authorized_keys
sudo chmod 600 /home/vpnadmin/.ssh/authorized_keys

Abra una segunda ventana de terminal y compruebe el acceso: ssh vpnadmin@SERVER_IP. Modifique la configuración del demonio SSH solo después de realizar una comprobación correcta.

sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak
sudo nano /etc/ssh/sshd_config

Agregue o modifique los siguientes parámetros. Si cambia el puerto SSH, no olvide abrirlo en el firewall antes de reiniciar el servicio.

PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
AllowUsers vpnadmin

sudo sshd -t
sudo systemctl restart ssh

Utilidades básicas, firewall y fail2ban

Instale herramientas de diagnóstico, firewall y protección contra ataques de fuerza bruta a contraseñas SSH. Incluso con la autenticación por contraseña desactivada, fail2ban es útil para reducir el ruido en los registros y bloquear fuentes sospechosas.

sudo apt install -y ca-certificates curl gnupg git jq vim \
  ufw fail2ban unattended-upgrades dnsutils htop

Abra únicamente los puertos necesarios. En este ejemplo, SSH funciona en el TCP 22 estándar, el panel web utiliza 80 y 443, WireGuard de NetBird utiliza UDP 51820, y coturn utiliza UDP/TCP 3478 y el rango de puertos relay UDP 49152–49200. Un rango reducido simplifica el firewall, pero limita el número de sesiones relay simultáneas; para un equipo pequeño es suficiente.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 80/tcp comment 'HTTP ACME'
sudo ufw allow 443/tcp comment 'HTTPS'
sudo ufw allow 51820/udp comment 'NetBird WireGuard'
sudo ufw allow 3478/tcp comment 'TURN TCP'
sudo ufw allow 3478/udp comment 'TURN UDP'
sudo ufw allow 49152:49200/udp comment 'TURN relay range'
sudo ufw enable
sudo ufw status verbose

Cree una configuración mínima de fail2ban. El valor de bantime es de una hora y, tras cinco intentos fallidos, la dirección se bloqueará temporalmente.

sudo tee /etc/fail2ban/jail.d/sshd.local > /dev/null <<'EOF'
[sshd]
enabled = true
maxretry = 5
findtime = 10m
bantime = 1h
EOF

sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

Active también las actualizaciones automáticas de seguridad de Ubuntu. No debe actualizar automáticamente las imágenes Docker: es mejor actualizarlas manualmente en una ventana programada, después de realizar una copia de seguridad y revisar las release notes.

sudo dpkg-reconfigure --priority=low unattended-upgrades
sudo systemctl status unattended-upgrades --no-pager

Instalación del software — paso a paso

En 2026, la forma más cómoda de desplegar NetBird self-hosted es mediante el paquete oficial de Docker Compose. Instala un conjunto coordinado de contenedores: management, signal, dashboard, PostgreSQL, coturn e identity provider. No compile imágenes desde repositorios aleatorios de terceros: el control plane contiene claves, tokens y datos sobre su red interna.

Antes de iniciar, compruebe la versión estable actual en el release oficial de NetBird en GitHub. Los comandos siguientes usan el script oficial de instalación getting-started.sh, que descarga el stack de la versión actual. Esto es más seguro que fijar un número de versión que podría estar obsoleto en el momento de leer el artículo.

Instalación de Docker Engine

Primero elimine los paquetes Docker antiguos en conflicto, si se instalaron desde el repositorio de Ubuntu. El comando no elimina sus datos Docker en /var/lib/docker, pero normalmente no existen en un servidor nuevo.

sudo apt remove -y docker.io docker-compose docker-compose-v2 \
  docker-doc podman-docker containerd runc 2>/dev/null || true

Agregue la clave GPG y el repositorio oficiales de Docker para Ubuntu 24.04.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Instale Docker Engine y el plugin Compose. A comienzos de 2026, utilice la rama estable actual de Docker Engine desde el repositorio oficial; la comprobación siguiente mostrará la versión realmente instalada.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker version
docker compose version

Permita al usuario vpnadmin ejecutar Docker sin sudo. Tras agregarlo al grupo, salga de la sesión SSH y vuelva a iniciar sesión; de lo contrario, el grupo no se aplicará.

sudo usermod -aG docker vpnadmin
exit

Después de volver a iniciar sesión, ejecute una prueba. El contenedor debe mostrar un mensaje de bienvenida y finalizar sin un error de permisos.

docker run --rm hello-world

Obtención del paquete oficial self-hosted

Cree un directorio para los archivos de infraestructura. No utilice /tmp: el sistema puede limpiarlo. El directorio /opt/netbird es práctico para servicios, pero asignaremos la propiedad al administrador para no trabajar como root.

sudo install -d -m 750 -o vpnadmin -g vpnadmin /opt/netbird
cd /opt/netbird

Defina el nombre de dominio completo. Debe resolver ya a la dirección IP del VPS; de lo contrario, la obtención automática del certificado TLS mediante Let's Encrypt no funcionará.

export NETBIRD_DOMAIN="netbird.example.com"
getent ahostsv4 "$NETBIRD_DOMAIN"

Descargue el installer oficial desde el latest release y revise primero las primeras líneas del script. La comprobación antes de ejecutarlo es especialmente importante para scripts que obtienen permisos para ejecutar contenedores Docker.

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh \
  -o getting-started.sh
less getting-started.sh
chmod 700 getting-started.sh

Ejecute el script con la variable de dominio. El bootstrap oficial crea la configuración de Compose, el archivo de entorno y la configuración inicial de NetBird self-hosted. Si el installer upstream solicita parámetros del identity provider o un email para ACME, indique una dirección válida y guarde todos los secretos emitidos en un password manager seguro.

NETBIRD_DOMAIN="$NETBIRD_DOMAIN" ./getting-started.sh

Tras finalizar la instalación, compruebe qué archivos se han creado. Los nombres pueden variar ligeramente entre versiones de NetBird, por lo que debe guiarse por la salida real del script y no crear un segundo stack de Compose manualmente.

cd /opt/netbird
find . -maxdepth 2 -type f | sort
docker compose ps

Comprobación de contenedores y registros

Todos los contenedores críticos deben estar en estado running o healthy. La primera obtención del certificado TLS puede tardar uno o dos minutos. Si los contenedores se reinician, consulte inmediatamente los registros en lugar de intentar ejecutar repetidamente la instalación sobre una configuración existente.

docker compose ps
docker compose logs --tail=100
docker compose logs --tail=100 management
docker compose logs --tail=100 coturn

Compruebe la disponibilidad de HTTPS. La opción -I solicita únicamente las cabeceras HTTP. Una respuesta 200, 302 o 307 normalmente significa que el reverse proxy y el dashboard están disponibles.

curl -I https://netbird.example.com
curl -fsS https://netbird.example.com/ > /dev/null && echo "HTTPS OK"

Configuración

Después del bootstrap, no se apresure a conectar todos los servidores. Primero fije la configuración, asegúrese de que TLS esté disponible y cree una cuenta administrativa independiente. Según la versión del paquete self-hosted de NetBird, la pantalla de inicio de sesión puede utilizar Zitadel integrado o un provider OpenID Connect externo. La lógica es la misma: el identity provider se encarga de la autenticación y NetBird management se encarga de los peers y las políticas de red.

Trabajo con el archivo de entorno

El installer oficial normalmente crea un archivo como setup.env, .env o similar. Contiene el dominio, las URL de los servicios, las contraseñas de PostgreSQL, los secretos OIDC y las credenciales TURN. Restrinja el acceso a este archivo: los permisos 600 son obligatorios, ya que la filtración de variables permite tomar el control del control plane.

cd /opt/netbird
ls -la
find . -maxdepth 2 -type f \( -name ".env" -o -name "setup.env" \) -print
chmod 600 .env 2>/dev/null || true
chmod 600 setup.env 2>/dev/null || true

A continuación se muestra un fragmento típico, no un archivo para reemplazar sin más. Los nombres de las variables pueden diferir en una versión concreta. No publique valores reales, no los guarde en Git ni los envíe a chatbots o tickets.

NETBIRD_DOMAIN=netbird.example.com
NETBIRD_MGMT_API_ENDPOINT=https://netbird.example.com:443
NETBIRD_MGMT_GRPC_API_ENDPOINT=https://netbird.example.com:443
NETBIRD_AUTH_AUDIENCE=netbird
POSTGRES_DB=netbird
POSTGRES_USER=netbird
POSTGRES_PASSWORD=CHANGE_TO_A_LONG_RANDOM_SECRET
TURN_MIN_PORT=49152
TURN_MAX_PORT=49200

Puede generar un secreto seguro localmente en el servidor. No utilice contraseñas cortas ni valores repetidos para PostgreSQL, Zitadel y TURN.

openssl rand -base64 48

TLS/HTTPS y Caddy

El quickstart oficial de NetBird normalmente incluye un reverse proxy y TLS automático. En muchas versiones se utiliza Caddy para ello, que escucha los puertos 80 y 443 y obtiene un certificado Let's Encrypt. Si el installer ya inició Caddy, no instale un segundo Caddy o Nginx en el host: dos procesos no podrán ocupar simultáneamente los puertos TCP 80 y 443.

Compruebe qué contenedor publica los puertos web. La salida debe incluir un servicio con el enlace 0.0.0.0:80->80 y 0.0.0.0:443->443.

docker compose ps
sudo ss -lntup | grep -E ':(80|443|3478|51820)\b'

Si administra deliberadamente el reverse proxy por su cuenta, un ejemplo de Caddyfile mínimo para el dashboard y la API de management es el siguiente. Obtenga los nombres y puertos internos reales de los contenedores del archivo Compose de NetBird suministrado. No copie el ejemplo hasta verificarlos mediante docker compose config.

netbird.example.com {
    encode zstd gzip

    handle /api/ {
        reverse_proxy management:33073
    }

    handle /ws-proxy/ {
        reverse_proxy signal:10000
    }

    handle {
        reverse_proxy dashboard:80
    }
}

Compruebe la fecha del certificado y el nombre en Subject Alternative Name. Un error de certificado casi siempre indica un registro DNS incorrecto, TCP 80/443 cerrado, la presencia de otro proxy o un intento de solicitar un certificado para un dominio que aún no se ha propagado en DNS.

echo | openssl s_client -connect netbird.example.com:443 \
  -servername netbird.example.com 2>/dev/null | \
  openssl x509 -noout -subject -issuer -dates

Creación del primer administrador

Abra https://netbird.example.com en el navegador. Cree el primer usuario mediante el identity provider integrado o el OIDC configurado. Después de iniciar sesión, compruebe que su usuario tenga el rol de administrador en el dashboard de NetBird. Active MFA de inmediato en el identity provider, especialmente si el panel está disponible desde Internet público.

Para servidores es más conveniente no utilizar un inicio de sesión interactivo personal. En el panel de NetBird, cree una Setup Key, limite su número de usos y su período de validez. Por ejemplo, para un único servidor de production, cree una clave de un solo uso y elimínela después de registrar el nodo.

Conexión de un Linux-peer

En el servidor que desea incluir en la mesh-VPN, instale el client oficial de NetBird. Antes de ejecutarlo, verifique el repositorio de paquetes y el comando con la documentación de su versión. Para Ubuntu/Debian, la opción habitual utiliza el script de instalación de NetBird, que añade el repositorio oficial.

curl -fsSL https://pkgs.netbird.io/install.sh | sudo bash
sudo apt update
sudo apt install -y netbird
netbird version

Sustituya SETUP_KEY por una setup key de un solo uso o limitada desde el panel. El parámetro --management-url indica a su agente que utilice su propio control plane, no el endpoint en la nube.

sudo netbird up \
  --management-url https://netbird.example.com \
  --setup-key SETUP_KEY

Compruebe el estado del agente. En una configuración correcta, el comando muestra el estado Connected, la IP de NetBird asignada y el número de peers. En algunas versiones, el comando puede mostrar información adicional sobre el signal server y relay.

sudo netbird status
ip addr show wt0 2>/dev/null || ip addr | grep -A2 -B2 netbird

Grupos, políticas y ACL mínimo

No deje la red en modo «todos ven a todos» si contiene servidores de production. Cree los grupos admins, developers, prod-servers y staging. Añada peers a los grupos según su finalidad, no según el nombre del empleado: así resulta más fácil mantener las reglas al cambiar dispositivos y roles.

Una política mínima puede permitir a los administradores acceder a todos los servidores por SSH, a los desarrolladores solo a staging y a los servidores de production realizar conexiones salientes entre sí únicamente por los puertos necesarios. Las políticas se crean en el Dashboard, en la sección Access Control. Para empezar, utilice una regla a nivel de red y luego restrínjala gradualmente a grupos y puertos.

Comprobación de la conexión mesh

Conecte al menos dos dispositivos peer. En el dashboard, encuentre la IP de NetBird del segundo dispositivo y, a continuación, ejecute ping y SSH a través del túnel. Si ping está prohibido por la política, compruebe el puerto de aplicación necesario mediante nc o curl.

ping -c 4 100.64.0.10
nc -vz 100.64.0.10 22
ssh [email protected]

Para comprobar que el acceso se realiza específicamente a través de la VPN, conéctese a un servicio que el firewall permita solo mediante la interfaz de NetBird. En la máquina de destino puede ver las conexiones entrantes y la interfaz de ruta.

ip route get 100.64.0.10
sudo ss -tnp | grep ':22'

Ruta a una subred local y exit node

NetBird puede publicar rutas a redes situadas detrás de un peer. Por ejemplo, un servidor de oficina con acceso a 192.168.50.0/24 puede convertirse en un routing peer. Para ello, se activa el IP forwarding en él, y la ruta se añade en el Dashboard y se asigna al grupo destinatario.

sudo tee /etc/sysctl.d/99-netbird-forwarding.conf > /dev/null <<'EOF'
net.ipv4.ip_forward=1
net.ipv6.conf.all.forwarding=1
EOF

sudo sysctl --system

Después de activar forwarding, configure el firewall/NAT de acuerdo con su esquema. No publique toda la subred doméstica sin ACL: primero permita el acceso solo al grupo de administradores. Un exit node, a través del cual el cliente envía todo el tráfico de Internet, requiere una configuración de NAT especialmente cuidadosa, monitorización del tráfico y comprensión de las consecuencias legales de utilizar una IP pública.

Copias de seguridad y mantenimiento

Los contenedores de NetBird se pueden recrear, pero los datos del control plane son difíciles de recuperar sin una copia de seguridad. El principal activo es PostgreSQL: contiene usuarios, peers, políticas, rutas, configuraciones y datos relacionados del identity provider. Guarde por separado los archivos Compose, los archivos de entorno, los datos de Caddy y todas las claves OIDC/TURN.

Qué se debe respaldar

• Un volcado de PostgreSQL en formato lógico pg_dump.
• El directorio /opt/netbird sin archivos temporales ni Docker image layers.
• Docker volumes, si almacenan datos de PostgreSQL, Zitadel y Caddy.
• Los archivos .env, setup.env, Compose YAML y Caddyfile.
• Secretos del identity provider, recovery codes MFA y documentación de los registros DNS.
• La lista de setup keys y usuarios administrativos, pero no las claves activas en texto plano.

Antes de configurar la automatización, averigüe los nombres del contenedor PostgreSQL y del volume. Esto es importante: el nombre puede no ser simplemente postgres. El comando siguiente mostrará los servicios y los volumes conectados.

cd /opt/netbird
docker compose ps
docker compose config --services
docker volume ls

Instalación de restic y preparación del almacenamiento

Guardar la única copia en el mismo VPS no tiene sentido: si se elimina el servidor, falla el disco o se compromete el acceso root, puede perderse junto con los datos. Utilice almacenamiento de objetos compatible con S3, un backup-VPS separado mediante SFTP u otro servidor independiente.

A continuación se utiliza restic con S3. Sustituya los valores por las credenciales de su almacenamiento. La contraseña del repositorio restic debe almacenarse fuera del propio VPS, por ejemplo, en un password manager. Tras la inicialización, elimine las variables exportadas del interactive shell history o utilice un archivo protegido solo para root.

sudo apt install -y restic
sudo install -d -m 700 /root/.config/restic
sudo nano /root/.config/restic/netbird.env
sudo chmod 600 /root/.config/restic/netbird.env

export RESTIC_REPOSITORY="s3:https://s3.example.com/netbird-backups"
export RESTIC_PASSWORD="REPLACE_WITH_LONG_UNIQUE_RESTIC_PASSWORD"
export AWS_ACCESS_KEY_ID="REPLACE_WITH_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="REPLACE_WITH_SECRET_KEY"

Inicialice el repositorio una vez. El comando creará una estructura cifrada de repositorio de backup.

sudo bash -c 'source /root/.config/restic/netbird.env && restic init'

Script de copia de seguridad automática

Cree el script. Genera un volcado de PostgreSQL en un directorio temporal, guarda la configuración, envía los datos a restic y elimina los volcados locales con más de siete días. Sustituya postgres y netbird por el nombre real del servicio y el nombre de la base de datos de su archivo Compose.

sudo tee /usr/local/sbin/backup-netbird.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

source /root/.config/restic/netbird.env

STACK_DIR="/opt/netbird"
BACKUP_DIR="/var/backups/netbird"
DATE="$(date +%F_%H-%M-%S)"
PG_SERVICE="postgres"
PG_DATABASE="netbird"
PG_USER="netbird"

mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"

cd "$STACK_DIR"

docker compose exec -T "$PG_SERVICE" \
  pg_dump -U "$PG_USER" -Fc "$PG_DATABASE" \
  > "$BACKUP_DIR/postgres_${DATE}.dump"

restic backup \
  "$BACKUP_DIR" \
  "$STACK_DIR/.env" \
  "$STACK_DIR/setup.env" \
  "$STACK_DIR/docker-compose.yml" \
  --tag netbird --tag postgres

restic forget --tag netbird \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

find "$BACKUP_DIR" -type f -name '.dump' -mtime +7 -delete
EOF

sudo chmod 700 /usr/local/sbin/backup-netbird.sh

sudo /usr/local/sbin/backup-netbird.sh
sudo bash -c 'source /root/.config/restic/netbird.env && restic snapshots'

sudo tee /etc/cron.d/netbird-backup > /dev/null <<'EOF'
25 3    root /usr/local/sbin/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1
EOF

Verificación de la restauración

Una copia de seguridad que no se ha probado mediante restauración no puede considerarse funcional. Una vez por trimestre, levante una VM temporal, descargue el snapshot, restaure las configuraciones e intente importar PostgreSQL en un contenedor de prueba. No pruebe la restauración en la base de datos de production.

sudo bash -c 'source /root/.config/restic/netbird.env && restic check'
sudo bash -c 'source /root/.config/restic/netbird.env && restic restore latest --target /tmp/netbird-restore'

Actualizaciones de NetBird

Para una red pequeña, utilice una maintenance window: avise a los usuarios, haga una copia de seguridad, lea las release notes, actualice los contenedores y compruebe la conexión de dos peers. Un rolling update solo tiene sentido con varias instancias de control plane y una base de datos externa planificada; en un único VPS, una interrupción breve suele ser más segura y sencilla.

cd /opt/netbird
sudo /usr/local/sbin/backup-netbird.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100

No ejecute sin pensar docker system prune -a en un servidor de production: el comando puede eliminar imágenes necesarias para un rollback rápido. Conserve las versiones anteriores de las imágenes hasta completar la verificación. Tras la actualización, compruebe el login en el dashboard, el registro de un peer de prueba, el status de un cliente existente y la conectividad TURN desde una red con NAT.

Solución de problemas + FAQ

¿Por qué el navegador muestra un error de certificado TLS o el sitio no se abre?

Primero compruebe DNS: el comando dig +short netbird.example.com A debe devolver la IP de su VPS. Después, asegúrese de que TCP 80 y 443 estén abiertos y no estén ocupados por otro Nginx, Apache o Caddy: sudo ss -lntp. Consulte los logs del reverse proxy mediante docker compose logs. Para Let's Encrypt, el dominio debe ser accesible públicamente durante el HTTP-01 challenge. Si se utiliza proxy DNS/CDN, desactívelo temporalmente o configure DNS challenge.

El peer está registrado, pero el estado sigue siendo Disconnected. ¿Qué comprobar?

En el cliente, ejecute sudo netbird status y asegúrese de que la management URL apunte a su dominio. Compruebe la resolución DNS y la disponibilidad de HTTPS: curl -I https://netbird.example.com. En el servidor, abra los logs de los contenedores management y signal. Una causa frecuente es una URL externa incorrecta en el archivo de entorno, una setup key caducada o una policy/firewall que bloquea el HTTPS saliente del cliente. Tras corregirlo, ejecute sudo netbird down y de nuevo sudo netbird up.

Los dispositivos se ven entre sí en el panel, pero ping y SSH no funcionan. ¿Por qué?

Compruebe la política ACL en el Dashboard: que un peer esté en la red no implica la autorización automática de cualquier tráfico. Después, compruebe el firewall local del servidor de destino: UFW puede permitir SSH solo desde la interfaz pública o solo desde una subred concreta. Consulte la IP de NetBird de ambos peers y la ruta con el comando ip route get PEER_IP. Para el diagnóstico, cree temporalmente una regla restringida que permita TCP 22 entre dos grupos de prueba, no una regla global all-to-all.

¿Por qué la conexión funciona lentamente o pasa por relay?

Esto normalmente significa que los peers no pudieron establecer una ruta UDP directa y utilizan TURN. Compruebe la disponibilidad de UDP 3478, UDP 51820 y el rango relay UDP 49152–49200 en el VPS, incluido el firewall externo del proveedor. En redes domésticas y corporativas, la causa puede ser un NAT simétrico o el bloqueo de UDP. Consulte el status del cliente y los logs de coturn. Relay es un fallback normal, pero su velocidad depende del enlace del VPS y de la distancia a los usuarios.

¿Qué configuración mínima de VPS es adecuada?

Para una red personal de 3–10 dispositivos, bastan 1 vCPU, 2 GB de RAM, 25 GB de SSD e IPv4 público. Para una operación estable con PostgreSQL, dashboard, coturn y margen para actualizaciones, es mejor elegir 2 vCPU, 4 GB de RAM y 40–50 GB de NVMe. Si se esperan muchos clientes detrás de NAT, la capacidad del disco es menos importante que el ancho de banda y el tráfico UDP habilitado. Supervise la RAM, la CPU y el tráfico saliente tras la puesta en marcha.

¿Qué elegir para esta tarea: VPS o dedicated?

Para la mayoría de las redes self-hosted de NetBird, un VPS es suficiente. El control plane consume pocos recursos, y decenas de peers rara vez requieren hardware dedicado. Se necesita dedicated con tráfico TURN alto y constante, requisitos de aislamiento de hardware, varios cientos de usuarios activos o necesidad de ancho de banda garantizado. Un enfoque práctico es empezar con un VPS de 2–4 vCPU y mover TURN a una máquina separada si las métricas muestran que relay se ha convertido en una limitación.

¿Cómo añadir una ruta a una subred doméstica o de oficina?

Elija un peer que esté conectado simultáneamente a NetBird y a la red local, por ejemplo 192.168.50.0/24. En él, active net.ipv4.ip_forward=1, luego añada la ruta en el Dashboard y asigne los grupos que tendrán acceso a ella. Asegúrese de que existe una ruta de retorno: el router local conoce la ruta hacia la subred de NetBird o el routing peer realiza NAT. Comience con un único host o una subred pequeña y compruebe el acceso mediante reglas ACL.

¿Se puede eliminar un peer si se pierde el portátil?

Sí. Abra el Dashboard, busque el dispositivo en la lista de Peers y elimínelo o desactívelo. El Management server dejará de proporcionarle una configuración actualizada y el acceso a los recursos de red será revocado según la política. Además, cierre las sesiones del usuario en el identity provider, cambie las setup keys si podrían haberse guardado en el dispositivo y revise los audit events. No utilice setup keys permanentes con un número ilimitado de registros.

Conclusiones y siguientes pasos

Ahora dispone de un control plane de NetBird self-hosted con HTTPS, mesh-VPN WireGuard, fallback TURN, firewall básico y copias de seguridad de PostgreSQL. Esta arquitectura permite unir VPS, servidores domésticos y dispositivos del equipo en una red privada sin depender constantemente de un control plane externo en la nube.

1. Cree grupos por roles y sustituya las reglas de acceso amplias por las ACL mínimas necesarias.
2. Conecte monitorización de Docker, disco, certificados TLS y volumen de tráfico TURN.
3. Cuando aumente la carga, mueva coturn a un servidor independiente, añada una segunda región relay y pruebe regularmente la restauración desde la copia de seguridad.