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.

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 el desafío TLS-ALPN-01, que se responde en el puerto 443 y requiere un nombre que resuelva a este 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 del 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. Ejecutar el instalador antes de que se propague el DNS hace que la solicitud del certificado falle en el primer arranque. Además, varias validaciones fallidas consecutivas alcanzan los límites de tasa de Let's Encrypt, por lo que tendrá que esperar a que se restablezca el límite antes de volver a intentarlo.

Tres puertos deben estar accesibles desde Internet: TCP 80 para la redirección a HTTPS, TCP 443 para el dashboard, la API, el tráfico de señalización 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 servidor cuyo ufw status propio 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, de modo que dos peers puedan intentar establecer un túnel directo. Si bloquea UDP 3478, los peers todavía se conectan mediante el relay en TCP 443, por lo que nada parece estar averiado. Los peers que no pueden encontrar una ruta directa muestran Connection type: Relayed, y su tráfico atraviesa el VPS en lugar de ir directamente de peer a peer. Los peers de la misma LAN todavía pueden conectarse directamente mediante sus direcciones locales.

En cuanto al software, 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 instálelo primero. Si Docker es nuevo en este servidor, consulte primero Poner Docker Compose en funcionamiento en el 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 la versión. 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 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 4 escriben un fragmento de configuración y dejan el cableado a su cargo, mientras que la opción 5 escribe el archivo Compose, dashboard.env y config.yaml, y muestra la documentación de configuración en el terminal. Esto es correcto en un equipo que ya ejecuta un proxy, pero no en uno nuevo. La opción 0 solicita después una dirección de correo electrónico, que Traefik registra en su cuenta de Let's Encrypt. El aviso todavía la describe como una dirección para 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 log de Traefik y no en su bandeja de entrada.

Responda que no al servicio NetBird Proxy durante la primera instalación. Necesita otro registro DNS, un CNAME comodín *.netbird.example.com que apunte a netbird.example.com, y no aporta nada a una malla simple. El aviso 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 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 deben leer running, y el log del servidor debe estabilizarse en lugar de reiniciarse en bucle. Supervise el certificado por separado:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) es el protocolo que Traefik usa 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 ofrece 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 a su VPS y requiere mucho menos trabajo para delegarlo en un compañero que nunca va a abrir una terminal. Si realmente está comparando NetBird con Tailscale alojado, en lugar de compararlo con Headscale, ambos usan WireGuard internamente. Por eso, la comparación entre NetBird y Tailscale explica sus diferencias reales: quién administra el plano de control, cómo se escriben las reglas de acceso y cómo los relés transportan el tráfico.

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. Contrate 2 GB.

En un servidor pequeño se pueden omitir tres elementos sin riesgo. Rechace el servicio NetBird Proxy, que sirve para publicar servicios internos con nombres de host públicos y no tiene relación con la conexión entre peers. Omita CrowdSec, que el script sólo ofrece junto con el proxy y que conviene añadir más adelante en un servidor expuesto, no el primer día. Mantenga el almacén SQLite predeterminado en el volumen netbird_data y cambie a PostgreSQL sólo cuando distribuya el despliegue 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 peers cuyo NAT asigna un puerto diferente para cada destino nunca establecerán un túnel directo, por lo que 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 servidor ya no es suficiente, los relays son lo primero que debe trasladar fuera de él. 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 pueden 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 apunta a 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 autorizaciones fallidas por nombre de host, por cuenta y por 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 el servidor con el que se está comunicando realmente. Si aparece Management: Connected to https://api.netbird.io:443, significa que 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 estableciendo túneles directos, por lo que todo el tráfico atraviesa el 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 interactivo de conectividad) de cada peer, lo que indica hasta dónde llegó el intento. En algunas redes, el resultado disponible es únicamente el tráfico retransmitido y no existe ningún problema.

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

netbird status informa de un problema del 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. Para cualquier problema que no pueda identificar, 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 por mi cuenta?

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 después. 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 desplegar Zitadel o Keycloak antes de NetBird describen una configuración que ya no es necesaria, y seguirlas le obliga a administrar un servicio adicional completo.

¿Por qué todos mis pares 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 pares 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:. Cuando ambos pares están detrás de NAT que asigna un puerto diferente para cada destino, relayed es el resultado esperado y no indica una configuración incorrecta.

Mi cliente se conectó, pero el panel no muestra ningún par. ¿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:, por lo que 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 par 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 es sólo un 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 guarda su estado en archivos. NetBird es más fácil de entregar a personas que no usará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. Esos 2 GB son la cantidad que debe contratar. Rechace el servicio de proxy opcional durante la instalación. Esto también omite la solicitud de instalar CrowdSec. Mantenga el almacén SQLite predeterminado hasta que realmente necesite PostgreSQL.