Implantar VPN em servidores headless

O FreeGuard CLI funciona nativamente em servidores Linux headless sem necessidade de ambiente de desktop. Seja para proteger uma instância na nuvem, um laboratório doméstico ou rotear tráfego de contêineres via VPN, este guia abrange instalação, autenticação, configuração de serviço e monitoramento para implantações em servidores de produção.

Por que executar VPN em um servidor?

Servidores lidam com tráfego sensível: conexões com bancos de dados, chamadas de API, transferências de backup e comunicação entre serviços. Executar VPN no próprio servidor garante que todo o tráfego de saída seja criptografado sem configurar aplicações individuais.

Casos de uso comuns:

Instâncias na nuvem acessando APIs com restrição geográfica
Runners CI/CD que precisam de identidade de rede consistente
Serviços auto-hospedados que se beneficiam do mascaramento de IP
Servidores de desenvolvimento usados por equipes distribuídas

Instalação

Ubuntu / Debian

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

Ou instale pelo repositório 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

Ou use o repositório 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

Usuários do Alpine podem precisar instalar o libc6-compat primeiro:

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

Verificar instalação

freeguard --version

Autenticação headless

Em servidores sem navegador, você não pode usar o fluxo de login OAuth padrão. O FreeGuard CLI oferece autenticação por e-mail para ambientes headless.

freeguard login --method email

O CLI solicita que você insira o e-mail da conta. Um código de verificação é enviado para esse endereço. Insira o código no terminal para concluir a autenticação.

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

Para implantações automatizadas, use um token de serviço:

freeguard login --method token --token YOUR_SERVICE_TOKEN

Gere tokens de serviço no painel da conta. Os tokens podem ser limitados a servidores específicos e ter expiração configurável.

Verificar autenticação

freeguard status --json | jq '.authenticated'

Executar como serviço systemd

Para implantações em produção, execute o FreeGuard CLI como serviço systemd para iniciar no boot e reiniciar em caso de falha.

Criar o arquivo de serviço

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 status do serviço

sudo systemctl status freeguard

Ver logs

sudo journalctl -u freeguard -f

Scripting com --json e --no-color

Scripts de produção devem analisar saída estruturada em vez de texto legível por humanos.

Saída JSON

Todo comando suporta --json:

# Connection status
freeguard status --json

Saída:

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

Modo sem cores

Remova códigos de cor ANSI para arquivos de log limpos:

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

Exemplo de scripting

Um script de verificação de saúde que reconecta em caso de falha:

#!/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

Adicione ao cron para verificações regulares:

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

Monitoramento e verificações de saúde

Verificação de saúde básica

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

Retorna true ou false. Simples o suficiente para qualquer sistema de monitoramento.

Integração com ferramentas de monitoramento

Exporte o status para Prometheus, Datadog ou qualquer sistema de monitoramento que possa executar 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

Combine a verificação de saúde com seu sistema de alertas. Exemplo com um webhook simples:

#!/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

Considerações de segurança

Executar como root: O túnel VPN requer privilégios root para modificar rotas de rede. O serviço systemd executa como root por padrão.
Armazenamento de tokens: Tokens de serviço são armazenados em ~/.config/freeguard/. Garanta permissões de arquivo adequadas (chmod 600).
Regras de firewall: Se usar UFW ou iptables, garanta que a interface do túnel VPN esteja permitida.
Kill switch: Ative o kill switch para bloquear todo o tráfego se o VPN desconectar: freeguard config set kill-switch true.

Próximos passos

FreeGuard CLI — referência completa de comandos
Guia de workflow do desenvolvedor — integre o VPN nas suas ferramentas de desenvolvimento
Preços — implantações em servidores funcionam com qualquer plano

Última atualização: março de 2026