Cómo alojar un servidor VPN NetBird en un VPS

Qué ofrece alojar tú mismo el servidor VPN de NetBird

Alojar tú mismo el servidor VPN de NetBird coloca el plano de control en un VPS que administras: la parte que 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 tus máquinas. Lo que cambia es que ninguna empresa externa conserva el inventario de tus dispositivos ni gestiona tu flujo de inicio de sesión. Debes tener claro qué ventaja ofrece esto, porque un plano de control alojado tampoco conserva las claves que cifran tu tráfico, y lo que un servidor de coordinación puede hacer realmente si se ve comprometido es una lista más limitada de lo que la mayoría supone antes de leerla.

NetBird se sitúa entre dos conceptos que quizá ya conozcas. Es una red superpuesta en malla, por lo que los pares se conectan entre sí en lugar de enviar todo a través de una única puerta de enlace. También se puede alojar por completo en tu propia infraestructura, por lo que compite con Headscale, el servidor de control de Tailscale autohospedado. Si sólo has ejecutado un túnel con una única puerta de enlace, lee primero la diferencia entre WireGuard sin configuración adicional y una red superpuesta en malla, porque ese modelo mental es el que permite aprovechar el resto de esta página.

Si lo que realmente quieres es que todo tu tráfico salga por un único servidor, una malla requiere más componentes de los necesarios. Una VPN WireGuard sencilla en un VPS o un nodo de salida de Tailscale hacen eso con mucha menos infraestructura que mantener. Y si el objetivo es acceder a una única red privada en lugar de conectar máquinas entre sí, un enrutador de subredes de Tailscale en un VPS anuncia ese rango a una tailnet que ya tienes, sin necesitar ninguno de los componentes que se describen a continuación.

Qué ejecuta realmente la pila

El diseño cambió hace poco y la mayoría de los artículos antiguos describen el anterior. Verificado en octubre de 2026 con v0.80.0 y con v0.76.2, la versión fijada en esta guía, el script de inicio rápido escribe de forma predeterminada un archivo 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 las versiones anteriores 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 solicitud. El servicio NetBird Proxy publica servicios internos en 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 solo contenedor Docker, esto supone un aumento del 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.

Qué necesita antes de empezar

Un nombre de dominio público no es opcional. El panel, la API y el relay funcionan mediante HTTPS en el puerto 443, y Traefik obtiene su certificado de Let's Encrypt mediante el desafío TLS-ALPN-01, que se responde en el puerto 443 y requiere un nombre que resuelva a esta VPS desde Internet público. Una dirección IP sin nombre no funciona en este flujo.

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

dig +short netbird.example.com

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, las validaciones fallidas repetidas alcanzan los límites de frecuencia de Let's Encrypt. En ese caso, debe esperar a que el límite se restablezca antes de volver a intentarlo.

Tres puertos deben ser accesibles desde Internet: TCP 80 para la redirección a HTTPS; TCP 443 para el panel, la API, el tráfico de signal y relay y el desafío del certificado; 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 equipo cuyo propio ufw status parece correcto puede seguir rechazando conexiones.

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

En el sistema necesita Docker con el plugin Compose v2, además de jq y curl. El script comprueba Docker, Compose y jq, y se detiene si falta alguno. Usa curl sin comprobar que esté instalado, así que debe instalarlo primero. Si Docker es nuevo en este equipo, configure primero Docker Compose en funcionamiento en la VPS.

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

El comando de una sola línea documentado canaliza 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 una versión concreta. latest cambia, por lo que el mismo comando ejecutado con dos semanas de diferencia produce dos instalaciones distintas, y ningún archivo del disco registra cuál de ellas escribió la configuración. Descargue una versión etiquetada, léala y después ejecútela.

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 pregunta 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 4 escriben un fragmento de configuración y dejan el cableado a su cargo, mientras que la opción 5 sólo escribe el archivo Compose y muestra la documentación de configuración en el terminal. Esto es correcto en un equipo que ya ejecuta un proxy y no lo es en uno nuevo. La opción 0 solicita una dirección de correo electrónico que Traefik registra en su cuenta de Let's Encrypt. El mensaje todavía la describe como una dirección para recibir notificaciones de certificados, pero Let's Encrypt dejó de enviar correos de expiración el June 4, 2025, por lo que los problemas de renovación aparecen en el registro de Traefik y no en la bandeja de entrada.

No habilite el servicio NetBird Proxy durante la primera instalación. Requiere otro registro DNS, un CNAME comodín *.netbird.example.com que apunte a netbird.example.com, y no aporta nada a una malla sencilla. El mensaje de CrowdSec sólo aparece cuando el proxy está habilitado, por lo que rechazar el proxy también lo omite. Ambos se pueden añadir más adelante.

El script escribe en el directorio actual: docker-compose.yml, config.yaml con modo 600 y dashboard.env. Con el Traefik incluido, añade traefik-dynamic.yaml y proxy.env sólo cuando se habilita NetBird Proxy. Trate ese directorio como estado persistente, 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 deberían leer running y el registro del servidor debería estabilizarse, no reiniciarse en un bucle. Supervise el certificado por separado:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment, entorno de gestión automática de certificados) es el protocolo que Traefik utiliza para obtener el certificado. Los errores aquí casi siempre se deben a DNS o a que el puerto 443 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. Esa 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 repositorio de usuarios propio de NetBird, proporcionado por un proveedor de identidad integrado en el contenedor netbird-server. No interviene ningún servicio externo. Este es el cambio más importante respecto a la versión de NetBird autohospedada de hace un año. En aquel momento, una instalación operativa requería configurar primero Zitadel o Keycloak y copiar cuatro valores OIDC (OpenID Connect) en setup.env antes de que el servicio pudiera iniciarse.

Si el navegador muestra una advertencia sobre el certificado en lugar de la página de configuración, el certificado no se emitió. Corrija el problema antes de continuar, porque el dashboard se comunica con la API mediante el mismo nombre de host y falla de formas poco claras cuando 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 tanto, el gestor de paquetes se encarga del cliente en ambos casos. Si no quiere canalizar un script a 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 qué 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 compilado. El comando se ejecuta correctamente, la máquina obtiene una dirección y el panel 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 la red superpuesta. wt0 es la interfaz de WireGuard que crea NetBird y debe tener esa misma dirección.

Unir una segunda máquina sin intervención mediante una setup key

El inicio de sesión en el navegador no funciona en una máquina sin navegador ni nadie delante. Una setup key 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 caducidad 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 parámetro, el peer usa el nombre que tenga la máquina, 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 desconectados, lo que evita que queden entradas inactivas en la lista de peers.

Hay un límite que debe conocer antes de planificar el uso de setup keys: la caducidad o revocación de una clave impide nuevos registros, pero no desconecta las máquinas que ya se registraron con ella. Para retirar 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 un grupo reducido de 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 pegar de nuevo en el proveedor. Hay integraciones específicas para Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik y Pocket ID. Cualquier otro proveedor se configura como OIDC genérico. Si ya ejecuta Authentik como su sistema de inicio de sesión único autohospedado, esta es la opción que 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, seguirá teniendo 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 usted sigue usando los clientes oficiales de Tailscale. No existe una consola web oficial. Administra los usuarios y las claves de preautenticación con el comando headscale contra un archivo de configuración. Existen interfaces web de la comunidad, pero no forman parte del proyecto. Esto resulta adecuado si quiere mantener el estado en archivos y gestionar los cambios mediante control de versiones.

NetBird proporciona el producto completo: su propio cliente, su propio panel, un proveedor de identidad integrado y políticas de acceso que se editan en el navegador. Esto implica más componentes en su VPS y requiere mucho menos trabajo para delegar la administración en un colega que nunca 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 administrar los peers y quiere una consola y SSO sin tener que montarlos por separado. Antes de decidirse por uno de los dos, consulte qué incluye realmente el plan gratuito de Tailscale, porque un grupo no comercial de hasta seis usuarios no paga nada por un plano de control alojado, con dispositivos de usuario ilimitados y 50 recursos etiquetados desde el principio, y puede no tener ningún motivo para ejecutar uno. Una vez superado ese límite, la factura crece según el número de personas y no según el número de máquinas. Por eso, calcular cuánto cobraría Tailscale a su grupo le proporciona una cifra que puede comparar con el coste del VPS y las horas que requiere esta infraestructura.

¿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. El diseño anterior necesitaba entre 2 GB y 4 GB cuando la pila incluía una implementación completa de Zitadel. Contrate 2 GB. Ese margen adicional permite descargar imágenes nuevas durante una actualización mientras las antiguas siguen en el disco.

En un servidor pequeño, puede omitir tres componentes sin problemas. Rechace el servicio NetBird Proxy. Sirve para publicar servicios internos con nombres de host públicos y no interviene en las conexiones entre pares. Omita CrowdSec. El script sólo lo ofrece junto con el proxy. Es mejor añadirlo más adelante en un servidor expuesto que instalarlo 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 varias máquinas o encuentre problemas reales de concurrencia. La documentación indica que la migración puede hacerse más adelante.

El relay es el único componente que no puede omitir. Dos pares cuyo 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 servidor ya no sea suficiente, lo primero que debe trasladar son los relays. 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 lo que verá

El panel muestra una advertencia de certificado. Traefik no obtuvo un certificado. Ejecute docker compose logs traefik | grep -i acme. Hay dos causas posibles. dig +short netbird.example.com todavía no resuelve hacia este VPS, o TCP 443 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. El desafío se responde en 443, por lo que tener abierto el puerto 80 no ayuda en este caso. Corrija la causa antes de reintentar en un bucle, porque Let's Encrypt permite sólo cinco validaciones fallidas por nombre de host y hora. Si supera ese límite, no podrá reintentar hasta que se restablezca.

El cliente indica que se conectó, pero 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 vuelva a ejecutar sudo netbird up --management-url https://netbird.example.com.

Todos los peers muestran Connection type: Relayed. No se están formando 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. Esto indica hasta dónde llegó el intento. En algunas redes, relayed es el único resultado disponible y no indica ningún problema.

Un peer se une, pero no puede acceder a nada. Formar parte de la malla no significa que dos peers puedan comunicarse. Las políticas de acceso determinan esto, y un grupo sin ninguna política asociada no puede acceder a ningún recurso. Compruebe la política en el panel antes de depurar las rutas y los 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 la causa, 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

La instalación depende de dos elementos: 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 una copia de seguridad de ambos elementos juntos. config.yaml contiene la clave que cifra los datos almacenados, por lo que una copia de la base de datos sin esa clave se restaura sin datos legibles.

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 muestre. De lo contrario, docker run falla al crear silenciosamente un volumen vacío y no archiva nada. Mantenga los archivos de copia fuera del VPS. Si ya usa una herramienta de copias de seguridad, restic o BorgBackup gestiona la parte externa.

Actualizar el servidor consiste en descargar la imagen y recrear el contenedor:

docker compose pull
docker compose up -d
docker compose ps

Antes de confiar en este procedimiento, 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 tener una versión a la que volver si una actualización causa problemas. Los clientes se actualizan mediante el gestor de paquetes con el que se instalaron.

FAQ

¿Necesito mi propio proveedor de identidad para alojar NetBird?

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

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

No se están estableciendo conexiones directas. Por eso el tráfico pasa por el relay de su VPS. La causa habitual es que UDP 3478 esté bloqueado. Este 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, ejecute netbird status --detail de nuevo y lea la línea Direct:. En una red cuyo NAT asigna un puerto diferente para cada destino, relayed es el único resultado posible. No hay ningún error de configuración.

Mi cliente se conectó, pero el dashboard 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 su dashboard.

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

Ambos sustituyen un servidor de control alojado por uno que usted ejecuta. 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 dashboard de administración y la integración con proveedores de identidad en la misma pila. Headscale es más pequeño y mantiene 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 de NetBird alojado por cuenta propia?

El mínimo documentado es 1 CPU y 2 GB de memoria. Por tanto, 2 GB es la cantidad que debe contratar. 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 requerir un despliegue independiente. Rechace el servicio de proxy opcional durante la instalación. Esto también omite la solicitud de CrowdSec. Mantenga el almacén SQLite predeterminado hasta que realmente necesite PostgreSQL.