목차

, , , ,

WireGuard configuration

wg와 wg-quick에서 사용하는 WireGuard configuration file의 section, key, route 동작과 안전한 검증 절차를 설명한다.

Summary

File Location

/etc/wireguard/wg0.conf

interface 이름이 wg1이면 파일 이름도 wg1.conf로 맞춘다. private material을 포함하므로 root만 읽고 쓸 수 있게 제한한다. 

sudo chown root:root /etc/wireguard/wg0.conf
sudo chmod 600 /etc/wireguard/wg0.conf

Syntax

Interface keys

Key 의미 비고
PrivateKey local interface의 base64 private key 필수이며 노출 금지
ListenPort 수신 UDP port 생략하거나 0이면 임의 port 선택 가능
FwMark outgoing packet의 firewall mark 선택
Address interface에 부여할 CIDR address wg-quick 확장, 여러 값 가능
DNS interface 활성 중 사용할 DNS server 또는 search domain wg-quick 확장
MTU interface MTU 생략하면 wg-quick이 추론
Table route table 제어 auto, off 또는 table number
PreUp, PostUp interface 활성화 전·후 command 여러 번 지정 가능
PreDown, PostDown interface 비활성화 전·후 command 여러 번 지정 가능
SaveConfig 종료 시 runtime configuration 저장 기존 파일을 덮어쓸 수 있음

Peer keys

Key 의미 비고
PublicKey remote peer의 base64 public key peer마다 필수
PresharedKey 선택적 symmetric preshared key 양쪽이 동일해야 하며 노출 금지
AllowedIPs 이 peer로 보낼 destination과 이 peer에서 허용할 source CIDR 여러 값 가능
Endpoint remote HOST:PORT 또는 [IPv6]:PORT roaming peer는 생략 가능
PersistentKeepalive NAT/firewall mapping 유지 간격(초) 필요할 때 보통 25, 0은 비활성

Example

다음 값은 모두 문서용 placeholder다. 실제 key와 address plan으로 바꾸되 production 값을 wiki에 기록하지 않는다.

Server

[Interface]
Address = 10.20.0.1/24
ListenPort = 51820
PrivateKey = SERVER_PRIVATE_KEY
 
[Peer]
PublicKey = CLIENT_PUBLIC_KEY
PresharedKey = OPTIONAL_PRESHARED_KEY
AllowedIPs = 10.20.0.2/32

Client

[Interface]
Address = 10.20.0.2/32
PrivateKey = CLIENT_PRIVATE_KEY
 
[Peer]
PublicKey = SERVER_PUBLIC_KEY
PresharedKey = OPTIONAL_PRESHARED_KEY
Endpoint = vpn.example.com:51820
AllowedIPs = 10.20.0.0/24
PersistentKeepalive = 25
예제의 SERVER_PRIVATE_KEY, CLIENT_PRIVATE_KEY, OPTIONAL_PRESHARED_KEY는 literal 값이 아니다. 실제 secret을 채운 파일은 permission을 0600으로 제한하고 backup·전송 경로도 암호화한다.

AllowedIPs and Routing

AllowedIPs는 두 방향에서 의미가 있다.

route를 자동 추가하지 않으려면 설계를 검토한 뒤 다음처럼 설정할 수 있다. 

[Interface]
Table = off

이 경우 필요한 policy rule과 route를 운영자가 별도로 관리해야 한다.

Hooks and Firewall

hook 안의 %i는 interface 이름으로 치환된다. 

[Interface]
PostUp = firewall-command add rule for %i
PostDown = firewall-command remove rule for %i
위 command는 구조만 보여 주는 placeholder이며 실행 가능한 firewall 규칙이 아니다. 실제 rule은 사용하는 nftables, iptables 또는 firewalld 정책과 기존 ruleset을 기준으로 작성한다. PostDown에는 PostUp 변경을 되돌리는 대칭 동작을 둔다.

hook은 root 권한으로 실행된다. 외부 입력, command substitution, secret 출력 또는 검증하지 않은 script를 넣지 않는다.

SaveConfig

[Interface]
SaveConfig = true

SaveConfig = true이면 wg-quick down 시 현재 interface 상태가 configuration file에 저장되며 수동 편집 내용이 덮어써질 수 있다. 선언적 file을 source of truth로 관리한다면 일반적으로 생략하고 변경 전 backup을 보관한다.

Validation

File과 permission 검토

sudo stat -c '%a %U:%G %n' /etc/wireguard/wg0.conf
sudo wg-quick strip /etc/wireguard/wg0.conf

strip은 wg-quick 전용 key를 제거하고 wg에 전달될 configuration을 출력한다. secret이 terminal이나 log에 노출될 수 있으므로 출력 공유에 주의한다.

적용 전 복구 계획

sudo cp --preserve=mode,ownership /etc/wireguard/wg0.conf /etc/wireguard/wg0.conf.backup
sudo wg-quick up wg0
sudo wg show wg0
ip address show dev wg0
ip route show
원격 server에서 full tunnel, routing, forwarding 또는 firewall hook을 시험할 때는 console 접근과 sudo wg-quick down wg0 rollback 경로를 먼저 확보한다.

활성 interface에 wg 설정 반영

sudo wg syncconf wg0 <(sudo wg-quick strip wg0)

syncconf는 peer session을 불필요하게 초기화하지 않도록 현재 설정과 차이를 반영한다. 그러나 address, route, DNS, MTU와 hook 변경은 별도 lifecycle 처리가 필요할 수 있다.

Precedence

Troubleshooting

DNS 적용 실패

Linux의 wg-quick은 DNS 항목 처리에 resolvconf를 호출할 수 있다. command가 없거나 다른 resolver manager를 사용하면 DNS를 제거하고 NetworkManager 또는 systemd-resolved integration을 별도로 설계한다.

기존 route와 AllowedIPs에서 자동 생성된 route가 충돌하는지 확인한다. 같은 interface가 이미 올라와 있으면 먼저 현재 owner와 상태를 확인하고 무조건 삭제하지 않는다. 

sudo wg show
ip link show type wireguard
ip route show table all
systemctl status wg-quick@wg0 --no-pager

Permission 또는 key 오류

file permission, base64 key의 잘림·공백, local private key와 상대가 등록한 public key의 쌍을 확인한다. 실제 key를 diagnostic 출력이나 issue에 첨부하지 않는다.

Compatibility

See Also

History