Instalación y Configuración de NetBird VPN

NetBird es una solución VPN mesh basada en WireGuard que conecta dispositivos en una red privada segura sin configuración de puertos ni reglas de firewall complejas, con soporte opcional para SSO, control de acceso basado en grupos y un servidor de gestión self-hosted. A diferencia de WireGuard puro, NetBird automatiza el intercambio de claves y la gestión de peers, haciendo que la configuración de redes mesh privadas sea accesible sin conocimientos avanzados de redes. Esta guía cubre el despliegue completo de NetBird self-hosted.

Requisitos Previos

Servidor Linux accesible desde internet (Ubuntu 20.04+ o Debian 11+)
Dominio con registros DNS configurados
Docker y Docker Compose instalados
Puertos abiertos: 80, 443 (para el panel web), 3478/UDP, 49152-65535/UDP (para STUN/TURN)
Mínimo 1 GB RAM para el servidor de gestión

Instalar el Servidor de Gestión Self-Hosted

NetBird proporciona un script de instalación que configura todos los componentes necesarios:

# Descargar el script de instalación de NetBird
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh -o netbird-install.sh

# Revisar el script antes de ejecutarlo
cat netbird-install.sh

# Ejecutar la instalación
bash netbird-install.sh

El script instala y configura:

NetBird Management Server: servidor de coordinación y API
NetBird Signal Server: servidor de señalización para establecer conexiones P2P
NetBird Relay (TURN): para dispositivos detrás de NAT estricto
Zitadel: servidor de identidad (SSO/OIDC)
Nginx: proxy inverso con SSL

Instalación manual con Docker Compose

Para mayor control sobre la configuración:

# Crear directorio de trabajo
mkdir -p /opt/netbird
cd /opt/netbird

# Descargar la configuración de Docker Compose
curl -fsSL https://raw.githubusercontent.com/netbirdio/netbird/main/infrastructure_files/docker-compose.yml \
    -o docker-compose.yml

# Descargar la plantilla de configuración
curl -fsSL https://raw.githubusercontent.com/netbirdio/netbird/main/infrastructure_files/.env.example \
    -o .env

# Editar la configuración
nano .env

Variables principales en .env:

# .env - Configuración de NetBird

# Dominio principal de NetBird
NETBIRD_DOMAIN=vpn.tudominio.com

# Puertos del servidor TURN (para NAT traversal)
TURN_MIN_PORT=49152
TURN_MAX_PORT=65535

# Secreto para el servidor TURN
TURN_PASSWORD=$(openssl rand -base64 32)

# Configuración de Zitadel (identidad/SSO)
# Se configura automáticamente con el script

# Email del administrador de Zitadel
[email protected]
ZITADEL_ADMIN_PASSWORD=TuPasswordSeguro123!

Configuración Inicial del Servidor

# Iniciar los servicios
cd /opt/netbird
docker compose up -d

# Ver los logs durante el inicio (tarda 2-3 minutos)
docker compose logs -f

# Verificar que todos los servicios están corriendo
docker compose ps

# Verificar que el panel de administración responde
curl -I https://vpn.tudominio.com

Configurar el DNS

Necesitas los siguientes registros DNS apuntando a tu servidor:

# Registros DNS necesarios:
# A: vpn.tudominio.com → IP_DEL_SERVIDOR
# A: netbird.vpn.tudominio.com → IP_DEL_SERVIDOR
# A: signal.vpn.tudominio.com → IP_DEL_SERVIDOR

# Verificar resolución DNS
dig +short vpn.tudominio.com
dig +short netbird.vpn.tudominio.com

Acceder al panel de administración

Accede a https://vpn.tudominio.com
Autentícate con las credenciales de Zitadel configuradas
Crea tu cuenta de administrador si es la primera vez

Agregar Peers a la Red

Instalar el cliente NetBird en Linux

# Instalación con el script oficial
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# O con apt (Ubuntu/Debian)
curl -fsSL https://pkgs.netbird.io/apt/gpg.key | \
    sudo gpg --dearmor -o /usr/share/keyrings/netbird-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netbird-keyring.gpg] https://pkgs.netbird.io/apt stable main' | \
    sudo tee /etc/apt/sources.list.d/netbird.list
sudo apt update
sudo apt install netbird

# CentOS/Rocky
sudo yum-config-manager --add-repo https://pkgs.netbird.io/yum/netbird.repo
sudo dnf install netbird

# Verificar la instalación
netbird version

Conectar un peer al servidor self-hosted

# Obtener el token de acceso (Setup Key) desde el panel web:
# Dashboard > Setup Keys > Create Setup Key
# Copiar la clave generada

# Conectar el peer al servidor NetBird self-hosted
sudo netbird up \
    --management-url https://vpn.tudominio.com \
    --setup-key TU-SETUP-KEY-AQUI

# Verificar el estado de la conexión
netbird status

# Ver información detallada del peer
netbird status --detail

# Ver la IP asignada en la red NetBird (por defecto en 100.x.x.x)
ip addr show wt0

Instalar en macOS y Windows

# macOS
brew install netbirdio/tap/netbird
sudo netbird up --management-url https://vpn.tudominio.com --setup-key TU-KEY

# Windows (PowerShell como administrador)
# Descargar el instalador desde: https://pkgs.netbird.io/windows/x64/NetBird_Installer.exe
# O con winget:
winget install NetBird
netbird up --management-url https://vpn.tudominio.com --setup-key TU-KEY

Gestión de Setup Keys

# Las Setup Keys tienen dos tipos:
# - One-time: para un solo peer (más seguro)
# - Reusable: para múltiples peers (cómodo para automatización)

# Crear una Setup Key one-time via API
curl -X POST https://vpn.tudominio.com/api/setup-keys \
    -H "Authorization: Bearer $NETBIRD_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "servidor-produccion",
        "type": "one-off",
        "expires_in": 86400,
        "auto_groups": ["grupo-servidores"]
    }'

Políticas de Control de Acceso

NetBird usa una política de denegación por defecto: solo el tráfico explícitamente permitido entre peers puede circular.

Crear políticas desde el panel web

Ve a Access Control > Policies > Add Policy
Define:
- Nombre: "Servidores a Base de Datos"
- Fuente: Grupo "servidores-web"
- Destino: Grupo "bases-de-datos"
- Puertos: 5432 (PostgreSQL), 6379 (Redis)
- Protocolo: TCP

Gestión de grupos

# Crear grupos via API de NetBird
NETBIRD_TOKEN="tu-token-de-api"

# Crear grupo de servidores web
curl -X POST https://vpn.tudominio.com/api/groups \
    -H "Authorization: Bearer $NETBIRD_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "servidores-web"}'

# Crear grupo de bases de datos
curl -X POST https://vpn.tudominio.com/api/groups \
    -H "Authorization: Bearer $NETBIRD_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "bases-de-datos"}'

# Asignar un peer a un grupo
PEER_ID="id-del-peer"
GROUP_ID="id-del-grupo"

curl -X PUT "https://vpn.tudominio.com/api/peers/$PEER_ID" \
    -H "Authorization: Bearer $NETBIRD_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"groups\": [\"$GROUP_ID\"]}"

Listar peers y su estado

# Listar todos los peers en la red
curl https://vpn.tudominio.com/api/peers \
    -H "Authorization: Bearer $NETBIRD_TOKEN" | jq '.[] | {id, name, ip, connected}'

# Ver estado detallado de un peer
curl "https://vpn.tudominio.com/api/peers/$PEER_ID" \
    -H "Authorization: Bearer $NETBIRD_TOKEN" | jq '.'

Integración con SSO

NetBird soporta proveedores OIDC para autenticación de usuarios:

Configurar Google OAuth

# En la consola de Google Cloud:
# 1. APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client IDs
# 2. Application type: Web application
# 3. Authorized redirect URIs: https://vpn.tudominio.com/auth/callback

# Configurar en Zitadel (servidor de identidad de NetBird):
# 1. Acceder a https://vpn.tudominio.com (panel de Zitadel)
# 2. Identity Providers > Add Google
# 3. Ingresar Client ID y Client Secret

Acceso con usuario SSO

# Los usuarios pueden autenticarse con SSO desde el cliente
sudo netbird up --management-url https://vpn.tudominio.com
# Se abrirá el navegador para autenticación SSO

# Modo no interactivo (para servidores sin navegador)
# Usar Setup Keys en lugar de SSO
sudo netbird up \
    --management-url https://vpn.tudominio.com \
    --setup-key TU-SETUP-KEY

Rutas de Red

NetBird puede enrutar tráfico hacia redes privadas a través de peers que actúan como gateways:

# Configurar un peer como gateway de red
# En el panel web: Routes > Add Route

# O via API:
curl -X POST https://vpn.tudominio.com/api/routes \
    -H "Authorization: Bearer $NETBIRD_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "description": "Red privada oficina Madrid",
        "network": "192.168.10.0/24",
        "peer": "id-del-peer-gateway",
        "metric": 9999,
        "masquerade": true,
        "enabled": true,
        "groups": ["todos-los-peers"]
    }'

# El peer gateway debe estar conectado a ambas redes:
# - La red NetBird (100.x.x.x)
# - La red privada local (192.168.10.0/24)

# Verificar las rutas en un peer cliente
ip route show | grep 192.168.10

Solución de Problemas

El peer no se conecta

# Ver el estado detallado de la conexión
netbird status --detail

# Ver los logs del cliente NetBird
journalctl -u netbird -f

# Verificar conectividad con el servidor de gestión
curl -I https://vpn.tudominio.com/api/

# Verificar que los puertos STUN/TURN están accesibles
nc -uzv vpn.tudominio.com 3478

Los peers se ven pero no se comunican

# Verificar las políticas de acceso en el panel web
# Access Control > Policies

# En el peer de origen, verificar la tabla de rutas NetBird
ip route show | grep 100.

# Probar conectividad con ping
ping 100.x.x.x  # IP del peer destino

# Ver si hay políticas bloqueando el acceso
netbird debug

Los servicios de Docker no arrancan

cd /opt/netbird

# Ver el estado de los contenedores
docker compose ps

# Ver logs de errores
docker compose logs --tail=50

# Reiniciar servicios individuales
docker compose restart netbird
docker compose restart coturn

# Verificar que los puertos están disponibles
ss -tulpn | grep ':3478\|:443\|:80'

Latencia alta entre peers

# La latencia alta indica que se usa un relay en lugar de conexión directa
netbird status --detail
# Buscar "Relay" en la salida - si aparece, los peers no establecen conexión directa

# Verificar que el puerto UDP 22000 está accesible en ambos extremos
nc -uzv IP_PEER_REMOTO 22000

# Forzar reconexión para renegociar la ruta
sudo netbird down && sudo netbird up

Conclusión

NetBird simplifica enormemente la creación de redes VPN mesh privadas comparado con la configuración manual de WireGuard, manteniendo la misma base criptográfica sólida. La combinación de servidor self-hosted, control de acceso basado en grupos y soporte SSO lo convierte en una solución adecuada para equipos y empresas que necesitan conectividad segura entre servidores y dispositivos sin depender de servicios VPN de terceros. Su modelo de denegación por defecto garantiza que solo el tráfico explícitamente permitido circula entre peers.

Netbird VPN Installation and Configuration

On this page