WG-Quick 고급 사용법과 스크립트 자동화

개요

이 글은 wg-quick 고급 사용법과 스크립트 자동화를 실무 관점에서 설명한다. 기본 명령어는 알고 있다는 전제다. 처음 접하는 사람도 이해할 수 있도록 구성했다. 핵심은 자동화와 유지보수의 단순화다.

wg-quick의 역할과 한계

wg-quick은 WireGuard 인터페이스를 간편하게 올리고 내리는 도구다. 구성 파일을 읽어 네트워크 설정과 키를 적용한다. 그러나 복잡한 전처리나 사후 처리가 필요하면 스크립트를 연결해야 한다. 또한 systemd와 결합하면 재부팅 시 자동 복구를 기대할 수 있다.

고급 옵션 정리

환경 변수와 Include

wg-quick은 환경 변수를 통해 동적 값을 전달할 수 있다. 단일 설정 파일에 민감한 값을 두지 않기 위해 include 방식으로 분리하는 것이 안전하다. 예를 들어 공용 키나 DNS 설정을 별도로 관리하면 재사용성이 높아진다.

PersistentKeepalive와 MTU 조정

PersistentKeepalive는 NAT 환경에서 연결을 유지하는 데 유용하다. MTU 조정은 터널링 성능에 직접적인 영향을 준다. 네트워크 특성에 맞게 값을 조정하면 패킷 분할을 줄여 안정성을 개선할 수 있다.

pre-up, post-up, pre-down, post-down 스크립트 활용

wg-quick 설정 파일에서 up/down 훅을 지정해 특정 명령을 실행할 수 있다. 보통 라우팅 조정, 방화벽 규칙 추가, DNS 변경 등을 자동화한다. 이 방식은 수동 작업을 줄이고 재현 가능한 환경을 만든다.

기본 예제

#!/bin/bash
# /etc/wireguard/wg0.up
# 인터페이스가 올라갈 때 실행할 스크립트
ip route add 10.0.0.0/24 dev wg0
iptables -I FORWARD -i wg0 -o eth0 -j ACCEPT

이 스크립트를 wg-quick 설정의 post-up으로 등록하면 인터페이스 활성화 직후 라우트와 방화벽 규칙이 적용된다.

안전한 스크립트 작성 원칙

• 에러 발생 시 즉시 중단하도록 set -e 사용
• 로그를 남겨 문제 발생 시 원인 파악 가능하게 함
• 권한은 최소화하고 실행 권한을 명확히 설정

#!/bin/bash
set -euo pipefail
logger -t wg-quick "wg0 up hook start"
# 추가 명령

systemd와의 통합

wg-quick은 systemd 서비스 단위(wg-quick@.service)로 동작한다. 이 서비스를 사용자 정의 유닛이나 타이머와 결합해 자동화 수준을 높일 수 있다. 예를 들어 네트워크가 완전히 준비된 뒤에 인터페이스를 올리도록 설정하면 초기 부팅 문제를 피할 수 있다.

systemd 서비스 의존성 설정

사용 예시로 NetworkManager나 systemd-networkd가 완전히 활성화된 후 wg-quick가 시작되도록 단위를 수정할 수 있다. 이렇게 하면 race condition을 줄일 수 있다.

자동화 시나리오: VPN 복구와 모니터링

연결 끊김에 자동 대응하는 간단한 모니터링 스크립트를 만들면 가용성이 향상된다. 주기적으로 피어 상태를 점검하고 비정상 시 재시작 또는 알림을 보낸다.

#!/bin/bash
WG_IF=wg0
PEER_ALLOWED_IP=10.0.0.2
if ! ip -4 neigh show dev $WG_IF | grep -q $PEER_ALLOWED_IP; then
  logger -t wg-monitor "peer $PEER_ALLOWED_IP unreachable, restarting $WG_IF"
  systemctl restart wg-quick@${WG_IF}
fi

이 스크립트를 cron이나 systemd 타이머에 등록하면 자동 복구가 가능하다.

복잡한 라우팅과 다중 피어 자동화

대규모 환경에서는 여러 wg 인터페이스와 정책 기반 라우팅이 필요하다. 피어별로 routing table을 분리하고, up 훅에서 ip rule과 ip route를 등록하면 목적지별 트래픽 분리가 가능하다.

# 예: 피어1 전용 테이블 추가
ip rule add from 10.0.1.0/24 table 101
ip route add default via 10.0.1.1 dev wg1 table 101

보안 및 운영 팁

• 비밀키는 파일 권한으로 보호하고 환경변수로 주입하지 않음
• 로그는 민감정보를 노출하지 않도록 주의
• 스クリ프트는 작은 단위로 나누어 테스트하기

문제 해결 절차

접속 문제 발생 시 순서대로 점검한다.

• wg show로 인터페이스 상태 확인
• ip addr, ip route로 네트워크 설정 점검
• 로그(journalctl -u wg-quick@wg0) 확인

실용 예제: 부팅 시 자동 연결과 DNS 복원

[Unit]
Description=WireGuard via wg-quick
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/wg-quick up wg0
ExecStop=/usr/bin/wg-quick down wg0

[Install]
WantedBy=multi-user.target

이 단위는 네트워크가 준비된 이후 인터페이스를 활성화한다. 여기에 post-up 훅으로 DNS를 적용하면 DNS 누락 문제를 방지할 수 있다.

마무리

wg-quick 고급 사용법과 스크립트 자동화는 안정성과 관리 효율을 높인다. 작은 스크립트와 systemd 통합으로 재현 가능한 설정을 구축하면 운영 부담이 줄어든다. 실무에서 적용 가능한 구성과 점검 절차를 통해 안정적인 WireGuard 운영이 가능하다.