FreeGuard VPN
HomeVPN 노드가격 책정
헤드리스 서버에 VPN 배포하기
FreeGuard CLI는 데스크톱 환경 없이 헤드리스 Linux 서버에서 네이티브로 실행됩니다. 클라우드 인스턴스 보안, 홈 랩 보호, 컨테이너 트래픽의 VPN 라우팅 등 이 가이드는 프로덕션 서버 배포를 위한 설치, 인증, 서비스 구성 및 모니터링을 다룹니다.
Table of Contents

헤드리스 서버에 VPN 배포하기

FreeGuard CLI는 데스크톱 환경 없이 헤드리스 Linux 서버에서 네이티브로 실행됩니다. 클라우드 인스턴스 보안, 홈 랩 보호, 컨테이너 트래픽의 VPN 라우팅 등 이 가이드는 프로덕션 서버 배포를 위한 설치, 인증, 서비스 구성 및 모니터링을 다룹니다.

서버에서 VPN을 실행하는 이유

서버는 민감한 트래픽을 처리합니다: 데이터베이스 연결, API 호출, 백업 전송 및 서비스 간 통신. 서버 자체에서 VPN을 실행하면 개별 애플리케이션을 구성하지 않고도 모든 아웃바운드 트래픽이 암호화됩니다.

일반적인 사용 사례:

  • 지역 제한 API에 접근하는 클라우드 인스턴스
  • 일관된 네트워크 ID가 필요한 CI/CD 러너
  • IP 마스킹의 이점을 누리는 셀프 호스팅 서비스
  • 분산 팀이 사용하는 개발 서버

설치

Ubuntu / Debian

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

또는 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

또는 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

Alpine 사용자는 먼저 libc6-compat를 설치해야 할 수 있습니다:

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

설치 확인

freeguard --version

헤드리스 인증

브라우저가 없는 서버에서는 기본 OAuth 로그인 플로우를 사용할 수 없습니다. FreeGuard CLI는 헤드리스 환경을 위한 이메일 기반 인증을 제공합니다.

이메일 로그인

freeguard login --method email

CLI가 계정 이메일 입력을 요청합니다. 해당 주소로 인증 코드가 전송됩니다. 터미널에서 코드를 입력하여 인증을 완료합니다.

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

토큰 기반 로그인

자동화된 배포의 경우 서비스 토큰을 사용합니다:

freeguard login --method token --token YOUR_SERVICE_TOKEN

계정 대시보드에서 서비스 토큰을 생성하세요. 토큰은 특정 서버로 범위를 제한할 수 있으며 구성 가능한 만료 기간이 있습니다.

인증 확인

freeguard status --json | jq '.authenticated'

systemd 서비스로 실행

프로덕션 배포의 경우 FreeGuard CLI를 systemd 서비스로 실행하여 부팅 시 시작되고 실패 시 재시작되도록 합니다.

서비스 파일 생성

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

활성화 및 시작

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

서비스 상태 확인

sudo systemctl status freeguard

로그 보기

sudo journalctl -u freeguard -f

–json 및 --no-color를 사용한 스크립팅

프로덕션 스크립트는 사람이 읽을 수 있는 텍스트 대신 구조화된 출력을 파싱해야 합니다.

JSON 출력

모든 명령은 --json을 지원합니다:

# Connection status
freeguard status --json

출력:

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

색상 없음 모드

깨끗한 로그 파일을 위해 ANSI 색상 코드를 제거:

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

스크립팅 예제

실패 시 재연결하는 헬스 체크 스크립트:

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

정기적인 점검을 위해 cron에 추가:

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

모니터링 및 헬스 체크

기본 헬스 체크

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

true 또는 false를 반환합니다. 모든 모니터링 시스템에 충분히 간단합니다.

모니터링 도구와의 통합

Prometheus, Datadog 또는 셸 명령을 실행할 수 있는 모니터링 시스템으로 상태를 내보냅니다:

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

알림

헬스 체크를 알림 시스템과 결합합니다. 간단한 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

보안 고려사항

  • root로 실행: VPN 터널은 네트워크 경로를 수정하기 위해 root 권한이 필요합니다. systemd 서비스는 기본적으로 root로 실행됩니다.
  • 토큰 저장: 서비스 토큰은 ~/.config/freeguard/에 저장됩니다. 적절한 파일 권한을 확인하세요 (chmod 600).
  • 방화벽 규칙: UFW 또는 iptables를 사용하는 경우 VPN 터널 인터페이스가 허용되는지 확인하세요.
  • 킬 스위치: VPN이 연결 해제되면 모든 트래픽을 차단하는 킬 스위치를 활성화합니다: freeguard config set kill-switch true.

다음 단계

최종 업데이트: 2026년 3월