FreeGuard VPN
HomeNodi VPNPrezzi
Distribuzione VPN su server headless
FreeGuard CLI funziona nativamente su server Linux headless senza bisogno di un ambiente desktop. Che tu stia proteggendo un'istanza cloud, un laboratorio domestico o instradando il traffico dei container attraverso una VPN, questa guida copre installazione, autenticazione, configurazione del servizio e monitoraggio per distribuzioni su server di produzione.
Indice

Distribuzione VPN su server headless

FreeGuard CLI funziona nativamente su server Linux headless senza bisogno di un ambiente desktop. Che tu stia proteggendo un’istanza cloud, un laboratorio domestico o instradando il traffico dei container attraverso una VPN, questa guida copre installazione, autenticazione, configurazione del servizio e monitoraggio per distribuzioni su server di produzione.

Perché eseguire una VPN su un server?

I server gestiscono traffico sensibile: connessioni ai database, chiamate API, trasferimenti di backup e comunicazione tra servizi. Eseguire una VPN sul server stesso garantisce che tutto il traffico in uscita sia crittografato senza configurare le singole applicazioni.

Casi d’uso comuni:

  • Istanze cloud che accedono ad API con restrizioni geografiche
  • Runner CI/CD che necessitano di un’identità di rete coerente
  • Servizi self-hosted che beneficiano del mascheramento IP
  • Server di sviluppo utilizzati da team distribuiti

Installazione

Ubuntu / Debian

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

Oppure installa dal repository 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

Oppure usa il repository 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

Gli utenti Alpine potrebbero dover installare prima libc6-compat:

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

Verifica dell’installazione

freeguard --version

Autenticazione headless

Sui server senza browser, non puoi usare il flusso di accesso OAuth predefinito. FreeGuard CLI fornisce l’autenticazione via email per ambienti headless.

Accesso via email

freeguard login --method email

La CLI ti chiede di inserire l’email del tuo account. Un codice di verifica viene inviato a quell’indirizzo. Inserisci il codice nel terminale per completare l’autenticazione.

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

Accesso basato su token

Per distribuzioni automatizzate, usa un token di servizio:

freeguard login --method token --token YOUR_SERVICE_TOKEN

Genera token di servizio dalla tua dashboard dell’account. I token possono essere limitati a server specifici e hanno una scadenza configurabile.

Verifica dell’autenticazione

freeguard status --json | jq '.authenticated'

Esecuzione come servizio systemd

Per distribuzioni in produzione, esegui FreeGuard CLI come servizio systemd in modo che si avvii al boot e si riavvii in caso di errore.

Creare il file del servizio

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

Abilitare e avviare

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

Verificare lo stato del servizio

sudo systemctl status freeguard

Visualizzare i log

sudo journalctl -u freeguard -f

Scripting con --json e --no-color

Gli script di produzione dovrebbero analizzare l’output strutturato anziché il testo leggibile dall’uomo.

Output JSON

Ogni comando supporta --json:

# Connection status
freeguard status --json

Output:

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

Modalità senza colori

Rimuovi i codici colore ANSI per file di log puliti:

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

Esempio di scripting

Uno script di controllo salute che si riconnette in caso di errore:

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

Aggiungilo al cron per controlli regolari:

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

Monitoraggio e controlli di salute

Controllo di salute base

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

Restituisce true o false. Abbastanza semplice per qualsiasi sistema di monitoraggio.

Integrazione con strumenti di monitoraggio

Esporta lo stato verso Prometheus, Datadog o qualsiasi sistema di monitoraggio che può eseguire comandi 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

Avvisi

Combina il controllo di salute con il tuo sistema di avvisi. Esempio con un semplice webhook:

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

Considerazioni sulla sicurezza

  • Esecuzione come root: Il tunnel VPN richiede privilegi root per modificare le rotte di rete. Il servizio systemd viene eseguito come root per impostazione predefinita.
  • Archiviazione dei token: I token di servizio sono memorizzati in ~/.config/freeguard/. Assicurati che i permessi dei file siano appropriati (chmod 600).
  • Regole del firewall: Se usi UFW o iptables, assicurati che l’interfaccia del tunnel VPN sia consentita.
  • Kill switch: Abilita il kill switch per bloccare tutto il traffico se la VPN si disconnette: freeguard config set kill-switch true.

Prossimi passi

Ultimo aggiornamento: marzo 2026