WireGuard configuration

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

• Linux의 wg-quick up wg0은 기본적으로 /etc/wireguard/wg0.conf를 읽는다.
• [Interface]는 local interface를, 각 [Peer]는 remote peer 하나를 정의한다.
• Address, DNS, MTU, Table, hook command는 wg-quick 확장 항목이며 wg 자체의 configuration에는 포함되지 않는다.
• 실제 private key, preshared key, 공인 endpoint와 내부망 정보가 포함된 production configuration은 Git이나 wiki에 저장하지 않는다.

/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

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

[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

[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

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

• 송신 시 destination IP와 일치하는 peer를 선택한다.
• 수신 시 복호화된 packet의 source IP가 해당 peer에 허용됐는지 검사한다.
• wg-quick은 기본적으로 AllowedIPs에서 route를 추론해 routing table에 추가한다.
• 0.0.0.0/0 또는 ::/0은 full tunnel이며 default route 처리와 SSH 연결에 영향을 줄 수 있다.
• 여러 peer에 중복되는 대역을 무심코 배치하지 말고 각 host peer에는 가능한 한 구체적인 /32 또는 /128을 사용한다.

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

[Interface]
Table = off

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

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

[Interface]
PostUp = firewall-command add rule for %i
PostDown = firewall-command remove rule for %i

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

[Interface]
SaveConfig = true

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

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

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

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

• 같은 interface를 NetworkManager, systemd wg-quick@, 직접 실행한 wg-quick이 동시에 관리하지 않도록 owner를 하나로 정한다.
• wg set으로 적용한 runtime 변경은 file에 자동 병합되지 않는다.
• SaveConfig = true는 종료 시 runtime state를 file에 기록하므로 수동 file 변경보다 나중에 적용될 수 있다.
• package update 후 systemd unit과 installed manual이 달라졌는지 확인한다.

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

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

• 이 페이지의 file path와 systemd 예시는 주로 Linux wg-quick을 대상으로 한다.
• BSD, macOS, Windows client는 interface와 DNS·route integration 방식이 다르다.
• 배포판이나 tool version에 따라 지원 key와 helper dependency가 다를 수 있으므로 installed wg-quick(8) manual을 우선한다.

• WireGuard
• wg
• wg-quick
• NetworkManager
• firewalld
• wg(8) configuration format
• wg-quick(8) configuration extensions

• codex:: 2026-08-13 WireGuard configuration key, AllowedIPs routing, hooks, validation과 보안 지침을 추가했다.
• codex:: 2026-08-13 분리된 wg와 wg-quick command page를 연결했다.