FreeGuard VPN
InicioNodos VPNPrecios
Desplegar VPN en servidores headless
FreeGuard CLI se ejecuta de forma nativa en servidores Linux headless sin necesidad de entorno de escritorio. Ya sea que estés asegurando una instancia en la nube, protegiendo un laboratorio doméstico o enrutando el tráfico de contenedores a través de VPN, esta guía cubre la instalación, autenticación, configuración del servicio y monitorización para despliegues en servidores de producción.
Tabla de Contenidos

Desplegar VPN en servidores headless

FreeGuard CLI se ejecuta de forma nativa en servidores Linux headless sin necesidad de entorno de escritorio. Ya sea que estés asegurando una instancia en la nube, protegiendo un laboratorio doméstico o enrutando el tráfico de contenedores a través de VPN, esta guía cubre la instalación, autenticación, configuración del servicio y monitorización para despliegues en servidores de producción.

¿Por qué ejecutar VPN en un servidor?

Los servidores manejan tráfico sensible: conexiones a bases de datos, llamadas API, transferencias de copias de seguridad y comunicación entre servicios. Ejecutar VPN en el propio servidor garantiza que todo el tráfico saliente esté cifrado sin configurar aplicaciones individuales.

Casos de uso comunes:

  • Instancias en la nube que acceden a APIs con restricción geográfica
  • Runners de CI/CD que necesitan identidad de red consistente
  • Servicios autoalojados que se benefician del enmascaramiento de IP
  • Servidores de desarrollo utilizados por equipos distribuidos

Instalación

Ubuntu / Debian

curl -fsSL https://cli.freeguard.com/install.sh | bash

O instalar desde el repositorio APT:

curl -fsSL https://cli.freeguard.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/freeguard.gpg
echo "deb [signed-by=/usr/share/keyrings/freeguard.gpg] https://apt.freeguard.com stable main" | sudo tee /etc/apt/sources.list.d/freeguard.list
sudo apt update
sudo apt install freeguard-cli

CentOS / RHEL / Fedora

curl -fsSL https://cli.freeguard.com/install.sh | bash

O usar el repositorio RPM:

sudo rpm --import https://cli.freeguard.com/gpg.key
sudo tee /etc/yum.repos.d/freeguard.repo <<EOF
[freeguard]
name=FreeGuard CLI
baseurl=https://rpm.freeguard.com/stable
gpgcheck=1
gpgkey=https://cli.freeguard.com/gpg.key
EOF
sudo yum install freeguard-cli

Alpine Linux

curl -fsSL https://cli.freeguard.com/install.sh | bash

Los usuarios de Alpine pueden necesitar instalar libc6-compat primero:

apk add libc6-compat
curl -fsSL https://cli.freeguard.com/install.sh | bash

Verificar instalación

freeguard --version

Autenticación headless

En servidores sin navegador, no puedes usar el flujo de inicio de sesión OAuth predeterminado. FreeGuard CLI proporciona autenticación basada en correo electrónico para entornos headless.

Inicio de sesión por correo electrónico

freeguard login --method email

La CLI te solicita que ingreses el correo electrónico de tu cuenta. Se envía un código de verificación a esa dirección. Ingresa el código en la terminal para completar la autenticación.

$ freeguard login --method email
Enter your email: [email protected]
Verification code sent. Check your inbox.
Enter code: 483291
Login successful.

Inicio de sesión con token

Para despliegues automatizados, usa un token de servicio:

freeguard login --method token --token YOUR_SERVICE_TOKEN

Genera tokens de servicio desde tu panel de cuenta. Los tokens pueden limitarse a servidores específicos y tener expiración configurable.

Verificar autenticación

freeguard status --json | jq '.authenticated'

Ejecución como servicio systemd

Para despliegues en producción, ejecuta FreeGuard CLI como servicio systemd para que se inicie al arrancar y se reinicie en caso de fallo.

Crear el archivo de servicio

sudo tee /etc/systemd/system/freeguard.service <<EOF
[Unit]
Description=FreeGuard VPN
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/freeguard connect --server us-east --no-color
ExecStop=/usr/local/bin/freeguard disconnect
Restart=on-failure
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
EOF

Habilitar e iniciar

sudo systemctl daemon-reload
sudo systemctl enable freeguard
sudo systemctl start freeguard

Verificar estado del servicio

sudo systemctl status freeguard

Ver registros

sudo journalctl -u freeguard -f

Scripting con --json y --no-color

Los scripts de producción deben analizar salida estructurada en lugar de texto legible por humanos.

Salida JSON

Cada comando soporta --json:

# Connection status
freeguard status --json

Salida:

{
  "connected": true,
  "server": "us-east-1",
  "server_name": "New York",
  "protocol": "hysteria2",
  "uptime": 86400,
  "bytes_sent": 1048576,
  "bytes_received": 5242880
}

Modo sin colores

Elimina los códigos de color ANSI para archivos de registro limpios:

freeguard status --no-color >> /var/log/freeguard-status.log

Ejemplo de scripting

Un script de verificación de salud que reconecta en caso de fallo:

#!/bin/bash
STATUS=$(freeguard status --json 2>/dev/null)
CONNECTED=$(echo "$STATUS" | jq -r '.connected')

if [ "$CONNECTED" != "true" ]; then
  echo "$(date): VPN disconnected, reconnecting..." >> /var/log/freeguard-health.log
  freeguard connect --server us-east --json >> /var/log/freeguard-health.log 2>&1
fi

Agrégalo a cron para verificaciones regulares:

# Check VPN health every 5 minutes
*/5 * * * * /opt/scripts/freeguard-health.sh

Monitorización y verificaciones de salud

Verificación de salud básica

freeguard status --json | jq -r '.connected'

Devuelve true o false. Suficientemente simple para cualquier sistema de monitorización.

Integración con herramientas de monitorización

Exporta el estado a Prometheus, Datadog o cualquier sistema de monitorización que pueda ejecutar comandos shell:

#!/bin/bash
# prometheus-exporter.sh
STATUS=$(freeguard status --json)
CONNECTED=$(echo "$STATUS" | jq -r '.connected')
UPTIME=$(echo "$STATUS" | jq -r '.uptime')

if [ "$CONNECTED" = "true" ]; then
  echo "freeguard_connected 1"
  echo "freeguard_uptime_seconds $UPTIME"
else
  echo "freeguard_connected 0"
  echo "freeguard_uptime_seconds 0"
fi

Alertas

Combina la verificación de salud con tu sistema de alertas. Ejemplo con un webhook simple:

#!/bin/bash
CONNECTED=$(freeguard status --json | jq -r '.connected')
if [ "$CONNECTED" != "true" ]; then
  curl -X POST https://hooks.example.com/alert \
    -H "Content-Type: application/json" \
    -d '{"text": "FreeGuard VPN disconnected on '"$(hostname)"'"}'
fi

Consideraciones de seguridad

  • Ejecutar como root: El túnel VPN requiere privilegios de root para modificar las rutas de red. El servicio systemd se ejecuta como root por defecto.
  • Almacenamiento de tokens: Los tokens de servicio se almacenan en ~/.config/freeguard/. Asegúrate de tener los permisos de archivo adecuados (chmod 600).
  • Reglas de firewall: Si usas UFW o iptables, asegúrate de que la interfaz del túnel VPN esté permitida.
  • Kill switch: Habilita el kill switch para bloquear todo el tráfico si se desconecta el VPN: freeguard config set kill-switch true.

Próximos pasos

Última actualización: marzo de 2026