Alojar un servidor VPN de NetBird en un VPS

Qué ofrece alojar su propio servidor VPN de NetBird

Alojar su propio servidor VPN de NetBird coloca el plano de control en un VPS que usted administra. Esta parte mantiene la lista de pares, decide qué máquina puede acceder a cuál y ayuda a que dos pares se encuentren detrás de NAT (traducción de direcciones de red). Los túneles siguen usando WireGuard y están cifrados directamente entre sus máquinas. La diferencia es que ninguna empresa externa mantiene el inventario de sus dispositivos ni gestiona su proceso de inicio de sesión.

NetBird combina dos conceptos conocidos. Es una red de superposición en malla, por lo que los pares se conectan entre sí en lugar de enviar todo el tráfico a través de una única puerta de enlace. También se puede alojar por completo, por lo que compite con Headscale, el servidor de control de Tailscale autoadministrado. Si sólo ha utilizado un túnel con una única puerta de enlace, lea primero la diferencia entre WireGuard básico y una red de superposición en malla, porque ese modelo mental permite entender el resto de esta página.

Si lo que necesita realmente es un único servidor por el que salga todo su tráfico, una malla ofrece más componentes de los necesarios. Una VPN WireGuard básica en un único VPS o un nodo de salida de Tailscale cumplen esa función con mucha menos infraestructura que mantener.

Qué ejecuta realmente la pila

El diseño cambió recientemente y la mayoría de los documentos antiguos describen el anterior. En agosto de 2026, con la versión v0.76.2, el script de inicio rápido escribe de forma predeterminada un archivo de Compose con tres servicios.

• netbird-server proporciona la API de administración, el servicio de señalización, el relay con un listener STUN integrado y un proveedor de identidad integrado. En versiones anteriores, estos componentes eran contenedores independientes y el proveedor de identidad era una instalación independiente de Zitadel que había que preparar primero.
• dashboard es la consola web de administración.
• traefik termina TLS (seguridad de la capa de transporte) y solicita un certificado a Let's Encrypt durante el primer arranque.

Existen otros dos servicios que permanecen desactivados a menos que responda afirmativamente a una pregunta. El servicio NetBird Proxy publica servicios internos con nombres de host públicos. CrowdSec filtra el tráfico abusivo. Ninguno es necesario para crear una malla funcional y ambos consumen memoria en un equipo pequeño.

Si viene de wg-easy en un único contenedor Docker, esto aumenta el número de componentes. A cambio, obtiene políticas de acceso y cuentas por usuario, además de peers que se conectan directamente entre sí en lugar de hacerlo a través de una única gateway.

Lo que necesita antes de empezar

Un nombre de dominio público no es opcional. El dashboard, la API y el relay usan HTTPS en el puerto 443, y Traefik obtiene su certificado de Let's Encrypt mediante un desafío HTTP. Este desafío necesita un nombre que resuelva a este VPS desde Internet. Una dirección IP directa no funciona en este flujo.

Cree un registro A, netbird.example.com, que apunte a la dirección IPv4 pública del VPS y espere a que se propague antes de ejecutar cualquier comando.

dig +short netbird.example.com

El comando debe mostrar la dirección de su servidor. Si ejecuta el instalador antes de que se propague el DNS, la solicitud del certificado falla durante el primer arranque. Además, varias validaciones fallidas consecutivas alcanzan los límites de frecuencia de Let's Encrypt, por lo que tendrá que esperar una hora para volver a intentarlo.

Tres puertos deben ser accesibles desde Internet: TCP 80 para el desafío del certificado y la redirección a HTTPS, TCP 443 para el dashboard, la API, el tráfico de señalización y el relay, y UDP 3478 para STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Ábralos también en el firewall de red de su proveedor. En la mayoría de los paneles de VPS es un control independiente. Por eso un servidor cuyo propio ufw status parece correcto puede seguir rechazando conexiones.

STUN (session traversal utilities for NAT) permite que un peer conozca la dirección pública y el puerto que le asignó su propio NAT. Así, dos peers pueden intentar establecer un túnel directo. Si bloquea UDP 3478, los peers siguen conectándose mediante el relay a través de TCP 443, por lo que nada parece fallar. En su lugar, obtiene Connection type: Relayed en cada peer, y todo el tráfico atraviesa su VPS en vez de circular directamente entre los peers.

En el sistema también necesita Docker con el complemento Compose v2, además de jq y curl. El script comprueba que todos estén disponibles y se detiene si falta alguno. Si Docker es nuevo en este servidor, configure primero Docker Compose en el VPS.

Instalar el servidor NetBird con el script de inicio rápido

El comando de una sola línea documentado envía directamente la versión más reciente a un shell:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Fije la versión. latest cambia, por lo que el mismo comando ejecutado con dos semanas de diferencia produce dos instalaciones distintas. Además, ningún archivo local registra cuál de ellas escribió la configuración. Descargue una versión etiquetada, revísela y ejecútela después.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

El script solicita primero el dominio:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Después solicita cómo se gestionará TLS:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

Elija [0]. Las opciones 2 a 5 escriben un fragmento de configuración y dejan que usted configure la integración. Esto es correcto en un equipo que ya ejecuta un proxy, pero no en uno nuevo. La opción 0 solicita una dirección de correo de Let's Encrypt para enviar avisos de caducidad.

No habilite el servicio NetBird Proxy durante la primera instalación. Requiere dos registros DNS adicionales, proxy.netbird.example.com y el comodín *.proxy.netbird.example.com, y no aporta nada a una red mallada básica. Tampoco habilite CrowdSec. Puede añadir ambos más adelante.

El script escribe en el directorio actual: docker-compose.yml, config.yaml con permisos 600, dashboard.env y traefik-dynamic.yaml cuando elige el Traefik incluido. Trate ese directorio como datos de estado que debe conservar, porque config.yaml contiene la clave que cifra los datos del almacén. Perderla no se soluciona reinstalando.

docker compose ps
docker compose logs -f netbird-server

Todos los servicios deben leer running, y el registro del servidor debe estabilizarse en lugar de reiniciar en un bucle. Supervise el certificado por separado:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) es el protocolo que Traefik utiliza para obtener el certificado. Estos errores casi siempre se deben a problemas de DNS o a que el puerto 80 está cerrado.

Crear la primera cuenta de administrador

Abra https://netbird.example.com. En una instalación nueva, se muestra una página de configuración en lugar de un formulario de inicio de sesión. Introduzca una dirección de correo electrónico, un nombre y una contraseña. Después, haga clic en Create Account. Esta cuenta se convierte en la primera cuenta de administrador y la página redirige al formulario de inicio de sesión.

La cuenta se almacena en el propio almacén de usuarios de NetBird, proporcionado por un proveedor de identidad integrado en el contenedor netbird-server. No interviene ningún servicio externo. Este es el cambio principal respecto a la versión de NetBird autohospedada de hace un año. En aquella versión, una instalación funcional requería configurar primero Zitadel o Keycloak y copiar cuatro valores de OIDC (OpenID Connect) en setup.env. De lo contrario, nada llegaba a iniciarse.

Si el navegador muestra una advertencia sobre el certificado en lugar de la página de configuración, el certificado no se ha emitido. Corrija este problema antes de continuar. El dashboard se comunica con la API mediante el mismo nombre de host y puede fallar de formas confusas si el certificado no es válido.

Conecte su primer peer

Instale el cliente en cualquier máquina Linux, incluido el propio VPS si quiere incorporarlo a la malla:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

En Debian y Ubuntu, ese script configura el repositorio de paquetes de NetBird y después instala el cliente mediante apt, por lo que el gestor de paquetes termina administrándolo en cualquier caso. Si no quiere canalizar un script hacia un shell, guárdelo primero con curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh y léalo antes de ejecutar sh install.sh. En cualquier caso, confirme lo que se instaló:

apt-cache policy netbird

netbird es el cliente de línea de comandos y el daemon. netbird-ui es la aplicación de bandeja del escritorio, y un servidor sin interfaz gráfica no la necesita.

Ahora indique al cliente que use su servidor:

sudo netbird up --management-url https://netbird.example.com

Si omite --management-url, el cliente se registra en el servicio alojado de NetBird porque ese es el valor predeterminado incorporado en el binario. El comando se ejecuta correctamente, la máquina obtiene una dirección y el dashboard autohospedado permanece vacío. Esto confunde a casi todo el mundo la primera vez.

El comando muestra una URL que debe abrir en un navegador para completar el inicio de sesión. Después:

netbird status
ip addr show wt0

Lea cuatro líneas de netbird status: Management: Connected, Signal: Connected, una línea Relays: que informa de todos los relays disponibles y una línea NetBird IP: con una dirección del rango de overlay. wt0 es la interfaz WireGuard que crea NetBird y debe tener esa misma dirección.

Unir una segunda máquina sin intervención mediante una clave de configuración

El inicio de sesión en el navegador no funciona en una máquina sin navegador y sin nadie delante de ella. Una clave de configuración es un token de preautenticación que registra una máquina sin el paso interactivo. Cree una en el panel, en Setup Keys.

Hay dos tipos. Una clave de un solo uso autentica exactamente una máquina y después se consume. Una clave reutilizable registra varias máquinas, con un límite opcional sobre la cantidad. Ambas tienen una fecha de expiración y ambas pueden asignar automáticamente el nuevo peer a un grupo, de modo que las reglas de acceso de ese grupo se aplican en cuanto aparece la máquina.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname establece el nombre que se muestra en el panel. Sin este valor, el peer usa el nombre que la máquina se asigna a sí misma, y una flota de entradas llamadas ubuntu no resulta útil.

Para contenedores y agentes de compilación de corta duración, marque la clave como ephemeral al crearla. Los peers registrados con una clave ephemeral se eliminan automáticamente cuando llevan más de 10 minutos sin conexión. Así se evita que las entradas obsoletas permanezcan en la lista de peers.

Debe tener en cuenta un límite antes de planificar el uso de setup keys: la expiración o eliminación de una clave impide nuevos registros, pero no desconecta las máquinas que ya se registraron con ella. Para revocar el acceso de una máquina, debe eliminar ese peer.

¿Todavía necesita un proveedor de identidad independiente?

Para una instalación pequeña, no. El almacén de usuarios integrado gestiona las cuentas creadas desde el panel y es suficiente para unas pocas personas.

Necesita un proveedor de identidad externo si ya dispone de uno y no quiere mantener una segunda lista de usuarios. NetBird acepta cualquier proveedor compatible con OIDC. Registre un cliente OIDC confidencial en su proveedor y añádalo en el panel de NetBird con cuatro valores: nombre, ID de cliente, secreto de cliente y emisor. NetBird le proporciona una URL de redirección que debe copiar de nuevo en el proveedor. Hay integraciones específicas para Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik y Pocket ID. Los demás proveedores se configuran como OIDC genérico. Si ya ejecuta Authentik como su sistema de inicio de sesión único autohospedado, esta opción permite mantener una sola lista de cuentas en lugar de dos.

El inicio de sesión local sigue disponible después de añadir un proveedor, y todos los proveedores configurados aparecen en la página de inicio de sesión. Mantenga una cuenta de administrador local con una contraseña segura. Si la configuración de OIDC falla, todavía tendrá una forma de acceder.

NetBird o Headscale: ¿qué plano de control debería ejecutar?

Ambos eliminan la misma dependencia: el servidor de control alojado al que, de otro modo, sus clientes se conectarían. No tienen la misma estructura de proyecto.

Headscale vuelve a implementar el servidor de control de Tailscale y permite seguir usando los clientes oficiales de Tailscale. No existe una consola web oficial. La gestión de usuarios y claves de preautenticación se realiza con el comando headscale contra un archivo de configuración. Existen interfaces web de la comunidad, pero no forman parte del proyecto. Esta opción es adecuada si quiere mantener el estado en archivos y gestionar los cambios mediante control de versiones.

NetBird incluye el producto completo: su propio cliente, su propio panel, un proveedor de identidad integrado y políticas de acceso que se editan en un navegador. Esto añade más componentes al VPS, pero facilita mucho delegar la gestión en un compañero que no va a abrir un terminal.

Ejecute Headscale si ya utiliza clientes de Tailscale o si quiere el plano de control más pequeño posible. Ejecute NetBird si varias personas necesitan gestionar los pares y quiere una consola y SSO sin tener que ensamblarlas por separado.

¿Qué tamaño mínimo de VPS puede ejecutar esto?

El mínimo documentado es 1 CPU y 2 GB de memoria. Las notas del propio NetBird sitúan ahora el mínimo cerca de 1 GB de RAM, porque la gestión de usuarios es local, frente a los 2 GB a 4 GB que necesitaba el diseño anterior cuando una implementación completa de Zitadel formaba parte de la pila. Contrate 2 GB. Ese margen adicional permite que una actualización descargue imágenes nuevas mientras las antiguas todavía están en el disco.

En un equipo pequeño, es seguro omitir tres componentes. Rechace el servicio NetBird Proxy. Se utiliza para publicar servicios internos en nombres de host públicos y no tiene relación con la conexión entre peers. Rechace CrowdSec. Es preferible añadirlo más adelante a un equipo expuesto, no desde el primer día. Mantenga el almacén SQLite predeterminado en el volumen netbird_data. Cambie a PostgreSQL sólo cuando distribuya la implementación entre varios equipos o alcance una concurrencia real. La documentación indica que esta migración puede hacerse más adelante.

El relay es el único componente que no puede omitirse. Dos peers cuya NAT asigne un puerto diferente para cada destino nunca establecerán un túnel directo. Por tanto, el relay es la única ruta que permite que funcionen. Desactivarlo ahorra muy poca memoria y rompe las conexiones de una forma difícil de diagnosticar.

Cuando un solo equipo ya no sea suficiente, los relays son lo primero que debe trasladar a otro equipo. Un relay independiente se ejecuta con NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET y NB_ENABLE_STUN. El secreto compartido debe ser idéntico en el relay y en el servidor principal. De lo contrario, los clientes no podrán autenticarse en él.

Modos de fallo y qué verá

El panel muestra una advertencia de certificado. Traefik no obtuvo ningún certificado. Ejecute docker compose logs traefik | grep -i acme. Hay dos causas posibles. dig +short netbird.example.com todavía no apunta a este VPS, o TCP 80 está cerrado en algún punto entre Let's Encrypt y el contenedor, normalmente en el firewall de red del proveedor y no en ufw. Corrija la causa antes de reintentar en un bucle, porque las validaciones fallidas están sujetas a límites de tasa y no podrá volver a intentarlo durante una hora.

El cliente indica que se conectó y el panel está vacío. El cliente se registró en el servicio alojado de NetBird porque faltaba --management-url. Ejecute netbird status --detail y lea la línea Management:, que indica con qué servidor se está comunicando realmente. Si aparece Management: Connected to https://api.netbird.io:443, se conectó a la nube. Ejecute sudo netbird down y, después, sudo netbird up --management-url https://netbird.example.com de nuevo.

Todos los peers muestran Connection type: Relayed. No se están creando túneles directos, por lo que todo el tráfico atraviesa su VPS y añade un salto de latencia. Compruebe UDP 3478 en el firewall del VPS y en el firewall del proveedor, ya que STUN permite que un peer conozca su propia dirección y puerto públicos. netbird status --detail también muestra Direct: false y los tipos de candidatos ICE (establecimiento de conectividad interactiva) de cada peer, lo que indica hasta dónde llegó el intento. En algunas redes, relayed es el único resultado disponible y no hay ningún problema.

Un peer se une y no puede acceder a nada. Formar parte de la malla no significa que dos peers puedan comunicarse. Las políticas de acceso lo determinan, y un grupo sin ninguna política asociada no puede acceder a nada. Compruebe la política en el panel antes de empezar a depurar rutas y firewalls.

netbird status informa de un problema con el daemon. El servicio no está en ejecución. Use sudo netbird service status y sudo netbird service start. Los registros del cliente están en /var/log/netbird/client.log. Si no puede determinar el origen de un problema, netbird debug bundle --anonymize --system-info recopila los registros, el estado, las rutas, la configuración DNS y el estado del firewall en un único archivo.

Copias de seguridad y actualizaciones

Dos elementos contienen toda la instalación: el directorio que contiene docker-compose.yml y config.yaml, y el volumen de Docker que contiene la base de datos y las claves de cifrado. Haga copias de seguridad de ambos juntos. config.yaml contiene la clave que cifra los datos almacenados, por lo que una copia de la base de datos sin esa clave no se puede restaurar en un estado legible.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose antepone el directorio del proyecto a los nombres de los volúmenes, por lo que el volumen documentado como netbird_data suele aparecer como netbird_netbird_data. Ejecute primero docker volume ls y use el nombre que muestra, o docker run fallará al crear silenciosamente un volumen vacío y no archivará nada. Mantenga los archivos de copia de seguridad fuera del VPS. Si ya usa una herramienta de copias de seguridad, restic o BorgBackup se encarga de la parte externa.

La actualización del servidor consiste en descargar la imagen y recrear el servicio:

docker compose pull
docker compose up -d
docker compose ps

Antes de confiar en este proceso, ejecute docker compose config | grep image:. Cualquier etiqueta que indique latest debe fijarse a una versión, por el mismo motivo por el que fijó el script de instalación: debe saber qué se está ejecutando y disponer de una versión a la que volver si una actualización causa problemas. Los clientes se actualizan mediante el gestor de paquetes que los instaló.

FAQ

¿Necesito mi propio proveedor de identidad para alojar NetBird?

No. Las versiones actuales incluyen un almacén de usuarios integrado, por lo que puede crear la primera cuenta de administrador en el navegador en https://netbird.example.com y añadir usuarios desde el panel posteriormente. Un proveedor OIDC externo es opcional y puede añadirse más adelante con cuatro valores: nombre, ID de cliente, secreto de cliente y emisor. Las guías que indican implementar Zitadel o Keycloak antes de NetBird describen una configuración que ya no es necesaria. Seguirlas le obliga a mantener un servicio adicional completo.

¿Por qué todos mis peers muestran Connection type: Relayed?

No se están estableciendo conexiones directas, por lo que el tráfico pasa por el relay de su VPS. La causa habitual es que UDP 3478 esté bloqueado. Ese es el puerto STUN que usan los peers para descubrir su propia dirección y puerto públicos. Ábralo en el firewall del VPS y en el firewall de red independiente de su proveedor. Después, vuelva a ejecutar netbird status --detail y lea la línea Direct:. En una red cuyo NAT asigna un puerto diferente para cada destino, relayed es el único resultado posible y no hay ninguna configuración incorrecta.

Mi cliente se conectó, pero el panel no muestra ningún peer. ¿Qué ocurrió?

El cliente se registró en el servicio alojado de NetBird en lugar de hacerlo en su servidor. Esto ocurre cuando se omite --management-url. netbird status --detail muestra el servidor con el que se comunica en la línea Management:. Un valor como https://api.netbird.io:443 lo confirma. Ejecute sudo netbird down y después sudo netbird up --management-url https://netbird.example.com. El peer aparecerá en el panel.

¿En qué se diferencia NetBird alojado por cuenta propia de Headscale?

Ambos sustituyen un servidor de control alojado por uno que usted administra. Headscale sólo proporciona el plano de control. Se administra con el comando headscale y un archivo de configuración. No tiene una consola web oficial y controla los clientes oficiales de Tailscale. NetBird incluye su propio cliente, un panel de administración y la integración con proveedores de identidad en la misma pila. Headscale es más pequeño y sencillo de ejecutar, y conserva su estado en archivos. NetBird es más fácil de entregar a usuarios que no utilizarán un terminal.

¿Qué tamaño de VPS necesita un servidor NetBird alojado por cuenta propia?

El mínimo documentado es 1 CPU y 2 GB de memoria. Debe contratar 2 GB. El mínimo práctico bajó a aproximadamente 1 GB en las versiones recientes porque el proveedor de identidad ahora está integrado, en lugar de implementarse como un servicio independiente. Durante la instalación, rechace el proxy opcional y los servicios CrowdSec. Mantenga el almacén SQLite predeterminado hasta que realmente necesite PostgreSQL.