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ó recientemente y la mayoría de las guías antiguas 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 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 en el primer arranque.

Hay otros dos servicios que permanecen desactivados a menos que responda afirmativamente a una pregunta. 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 un desafío HTTP. Para ello necesita un nombre que resuelva a este VPS desde Internet. 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. 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 seguidas pueden alcanzar los límites de tasa 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 panel, 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 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 estar averiado. En su lugar, obtiene Connection type: Relayed en cada par, y todo el tráfico atraviesa su VPS en vez de ir directamente entre los pares.

En cuanto al software, necesita Docker con el complemento Compose v2, además de jq y curl. El script comprueba todos estos requisitos y se detiene si falta alguno. Si Docker es nuevo en este equipo, 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 y ningún archivo del disco registra cuál de ellas escribió la configuración. Descargue una versión etiquetada, léala 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 el cableado en sus manos. 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 de Let's Encrypt, que se utiliza para enviar avisos de expiración.

No active el servicio NetBird Proxy en la primera instalación. Necesita dos registros DNS adicionales, proxy.netbird.example.com y el comodín *.proxy.netbird.example.com, y no aporta nada a una malla básica. Tampoco active CrowdSec. Ambos componentes se pueden añadir más adelante.

El script escribe en el directorio actual: docker-compose.yml, config.yaml con modo 600, dashboard.env y traefik-dynamic.yaml si eligió el Traefik incluido. Trate ese directorio como estado persistente, porque config.yaml contiene la clave que cifra los datos almacenados. 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, no reiniciarse en un bucle. Supervise el certificado por separado:

docker compose logs traefik | grep -i acme

ACME (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 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. 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 con 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 cuántas puede registrar. 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 desconectados, lo que evita que las entradas obsoletas permanezcan en la lista de peers.

Debe conocer un límite antes de planificar el uso de setup keys: expirar o eliminar 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 permite seguir usando los clientes oficiales de Tailscale. No existe una consola web oficial. Los usuarios y las claves de preautenticación se administran 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 en su VPS y resulta mucho más fácil de delegar a un compañero 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 peers y quiere una consola y SSO sin tener que montarlos por separado. Antes de decidirse por una de las dos opciones, compruebe qué incluye realmente el plan gratuito de Tailscale, porque un grupo de hasta seis usuarios con dispositivos ilimitados no paga nada por un plano de control alojado y quizá no tenga ningún motivo para ejecutar uno. Por encima de ese límite, la factura aumenta según el número de personas y no según el número de máquinas, así que calcular cuánto cobraría Tailscale a su grupo le proporciona una cifra para compararla con el VPS y con las horas que requiere esta pila.

¿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 que una actualización descargue imágenes nuevas mientras las antiguas todavía están en el disco.

En un servidor pequeño, puede omitir tres componentes sin problemas. No instale el servicio NetBird Proxy. Sirve para publicar servicios internos con nombres de host públicos y no interviene en las conexiones entre peers. No instale CrowdSec. 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 esa migración puede hacerse más adelante.

El relay es el único componente que no puede omitir. Dos peers cuya NAT asigne un puerto distinto 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, los relays son el primer componente que debe trasladar a otro servidor. 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 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 frecuencia 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 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 (interactive connectivity establishment) 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 incorpora y no puede acceder a nada. Formar parte de la malla no significa que dos peers puedan comunicarse. Las políticas de acceso determinan ese comportamiento, 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. Para cualquier problema cuya causa 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 de archivado.

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 eso, 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 desplegar Zitadel o Keycloak antes de NetBird describen una configuración que ya no es necesaria. Seguirlas le obliga a mantener un servicio adicional.

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

No se están formando 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 y no hay ningún error de configuración.

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 ejecuta. Headscale sólo proporciona el plano de control. Se administra con el comando headscale y un archivo de configuración. No existe una consola web oficial y utiliza 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 mantiene 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 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 se redujo a aproximadamente 1 GB en las versiones recientes porque el proveedor de identidad ahora está integrado en lugar de desplegarse por separado. Omita el proxy opcional y los servicios de CrowdSec durante la instalación. Mantenga el almacén SQLite predeterminado hasta que realmente necesite PostgreSQL.