# WireGuard 터널 컨테이너 두 개로 만들기: 핸드셰이크

> 컨테이너 두 개 사이에 WireGuard 터널을 만들고, 정상 설정과 공개키를 잘못 적은 설정, 허용 주소를 잘못 적은 설정을 같은 점검으로 비교합니다. 핸드셰이크가 되어도 ping이 실패하는 경우와 터널 안의 내용이 겉에서 보이지 않는 것을 tcpdump로 확인하고, 결과를 종료 코드로 바꿉니다.

- 주소: https://copyandrun.com/blog/wireguard-two-containers-handshake/
- 분야: DevSecOps
- 발행일: 2026-10-30
- 태그: WireGuard, VPN, 터널, tcpdump, 핸드셰이크

VPN 터널은 설정이 틀려도 오류 문구가 거의 나오지 않습니다. 맞는 키로 맞는 주소를 허용했을 때만 통신이 되고, 틀리면 조용히 패킷이 사라집니다. 그래서 "연결됐다"를 무엇으로 판단할지가 중요합니다. 이 글에서는 컨테이너 두 개에 WireGuard를 올려 정상 설정과 틀린 설정 두 가지를 만들고, 핸드셰이크 시각과 ping 결과로 같은 점검을 적용합니다. 이어서 터널로 보낸 내용이 겉에서 정말 보이지 않는지 tcpdump로 대조합니다. 모두 내 PC의 컨테이너 안에서만 실행합니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker | 29.5.3 (Windows 11, Docker Desktop, Git Bash에서 실행) |
| 리눅스 커널 | 6.6.87.2-microsoft-standard-WSL2 (WireGuard 인터페이스 생성 가능) |
| wireguard-tools | v1.0.20260223 (`alpine` 컨테이너에 `apk`로 설치) |
| 그 밖의 도구 | `iproute2`, `tcpdump`, `netcat-openbsd` (같은 컨테이너에 설치) |
| 파이썬 | 3.12 (`wg show` 결과를 읽는 데만 사용) |

컨테이너에는 `NET_ADMIN` 권한만 주었고(`--privileged`는 쓰지 않음), 전용 네트워크 `osk-fd-wgnet`에만 연결했습니다. 이 커널에서 인터페이스가 만들어지는지는 `ip link add wg0 type wireguard`로 먼저 확인했습니다. 다른 환경에서는 커널에 WireGuard가 없을 수 있습니다.

## 1. 구성

| 이름 | 실제 주소(컨테이너 네트워크) | 터널 주소 |
|---|---|---|
| `osk-fd-wga` (A) | 네트워크가 정한 주소 | `10.8.0.1/24` |
| `osk-fd-wgb` (B) | 네트워크가 정한 주소 | `10.8.0.2/24` |

각 컨테이너는 개인 키를 만들고 공개키를 서로 알려 줍니다. A에는 B의 공개키와 보낼 곳(`endpoint`)인 B의 실제 주소를, B에는 A의 공개키와 A의 실제 주소를 설정합니다. 포트는 양쪽 모두 UDP 51820입니다. 키는 실행할 때마다 새로 만들고 어디에도 저장하지 않으며, 개인 키를 명령행 인자와 표준 입력으로 넘기는 방식이라 시험 환경에서만 써야 합니다.

## 2. 세 가지 설정과 같은 점검

점검은 두 가지를 봅니다. `wg show wg0 dump`의 마지막 핸드셰이크 시각과, A에서 `10.8.0.2`로 보낸 ping 결과입니다. 둘 다 정상이어야 종료 코드 0입니다.

| 경우 | 설정 | 기대 |
|---|---|---|
| 1. 정상 | 서로의 공개키와 허용 주소가 맞음 | 핸드셰이크 있음, ping 성공 |
| 2. 공개키 오류 | A가 B의 공개키 자리에 엉뚱한 키를 적음 | 핸드셰이크 없음, ping 실패 |
| 3. 허용 주소 오류 | B가 A에게 허용한 주소를 `10.9.9.9/32`로 잘못 적음 | 핸드셰이크 있음, ping 실패(?) |

3번의 결과가 이 글에서 가장 알아 둘 만한 부분이라 물음표를 붙였습니다. 실제 결과는 다음과 같았습니다.

```
## 1. 정상 설정
  핸드셰이크 2초 전  받음 348B  보냄 404B  허용 주소 10.8.0.2/32
  ping 성공
  종료 코드 0
## 2. A 가 B 의 공개키를 잘못 적음
  핸드셰이크 없음  받음 0B  보냄 148B  허용 주소 10.8.0.2/32
  ping 실패
  종료 코드 1
## 3. B 가 A 의 주소를 잘못 허용함
  핸드셰이크 4초 전  받음 92B  보냄 404B  허용 주소 10.8.0.2/32
  ping 실패
  종료 코드 1
```

![wg_demo.sh 실행 결과에서 정상 설정은 핸드셰이크 있음과 ping 성공으로 종료 코드 0, 공개키 오류는 핸드셰이크 없음과 받은 바이트 0으로 종료 코드 1, 허용 주소 오류는 핸드셰이크는 있지만 ping 실패로 종료 코드 1인 것을 확인합니다.](https://copyandrun.com/img/wireguard-two-containers-handshake/01-wireguard-핸드셰이크-세-경우.png)

- **2번은 보내기만 했습니다.** A는 148바이트(첫 핸드셰이크 요청)를 보냈지만 받은 것이 0바이트이고 핸드셰이크 시각이 없습니다. 상대가 키가 맞지 않는 요청을 응답 없이 버리는 모습입니다.
- **3번은 핸드셰이크가 되었는데 ping이 실패했습니다.** 받은 바이트가 92로 핸드셰이크 응답까지만 왔고 ping 응답은 오지 않았습니다. B가 A의 주소를 허용 목록에 두지 않아 B가 A에게 보내려는 응답이 걸러진 것으로 보이며, B 쪽의 카운터까지는 확인하지 않았습니다.
- **그래서 핸드셰이크만으로 "연결됨"이라고 판단하면 안 됩니다.** 키가 맞는지(핸드셰이크)와 주소가 맞는지(허용 주소, 실제 통신)는 별개입니다.

## 3. 터널 안의 내용은 겉에서 보이는가

정상 설정으로 복구한 뒤, A의 `eth0`에서 B로 향하는 패킷을 `tcpdump`로 저장하면서 같은 문자열 `SECRETMARKER`를 두 가지 길로 보냈습니다.

- 터널 안: `10.8.0.2:9000`으로 TCP 전송
- 터널 밖: B의 실제 주소 `:9001`로 일반 TCP 전송

| 확인 | 결과 |
|---|---|
| 터널로 오간 UDP 51820 패킷 | 10개 |
| 포트 9000(터널 안)으로 `SECRETMARKER`가 겉에 보인 횟수 | 0 |
| UDP 51820 패킷 안에 `SECRETMARKER`가 보인 횟수 | 0 |
| 포트 9001(터널 밖)으로 `SECRETMARKER`가 겉에 보인 횟수 | 1 |

![터널 안으로 보낸 문자열은 겉에서 0번 보이고 UDP 51820 패킷은 길이 148, 92, 96의 암호화된 덩어리이며, 터널 밖으로 보낸 같은 문자열은 일반 TCP 패킷에서 그대로 보이는 것을 확인합니다.](https://copyandrun.com/img/wireguard-two-containers-handshake/02-wireguard-겉-패킷-비교.png)

같은 문자열을 보냈는데 터널 밖의 길에서는 한 번 보이고 터널 안의 길에서는 겉에 나타나지 않았습니다. 이 대조가 있어야 "안 보인다"의 이유가 "캡처가 잘못되어서"가 아니라 "암호화되어서"라고 말할 수 있습니다. 겉에서 보이는 것은 UDP 51820의 길이 148, 92, 96짜리 패킷뿐이었습니다. 앞의 둘은 핸드셰이크의 요청과 응답으로 보이며, 패킷 종류별 해석은 WireGuard 문서와 대조하지 않았습니다.

## 4. 점검을 종료 코드로

`wg_summary.py`는 `wg show wg0 dump`를 표준 입력으로 받아 핸드셰이크가 없거나 `--ping 0`이면 종료 코드 1로 끝납니다. 첫 줄에는 개인 키가 들어 있어서 읽지 않고 버립니다. 같은 스크립트를 세 경우에 똑같이 적용한 결과가 0, 1, 1이었습니다. 운영에서는 핸드셰이크가 180초 넘게 없으면 문제라고 보는 식으로 시간 기준을 정하는데, 이 글에서는 시간 기준을 따로 시험하지 않았습니다. ping 실패와 핸드셰이크 없음을 다른 알림으로 나누는 것도 해 보지 않았습니다.

## 전체 코드

전체를 한 번에 돌리는 스크립트입니다. 같은 폴더의 `wg_summary.py`가 필요합니다.

```bash
# wg_demo.sh
#!/usr/bin/env bash
# 컨테이너 두 개 사이에 WireGuard 터널을 만들고, 정상 설정과 틀린 설정 두 가지를 같은 방법으로 점검한다.
# 준비: Docker(Linux 컨테이너, WireGuard 를 지원하는 커널), python, 같은 폴더에 wg_summary.py.
# 주의: 키는 시험용으로 매번 새로 만들며 어디에도 저장하지 않는다.
# 실행(Git Bash): bash wg_demo.sh   (약 2분)
export MSYS_NO_PATHCONV=1
NET=osk-fd-wgnet; A=osk-fd-wga; B=osk-fd-wgb
cleanup() { docker rm -f $A $B >/dev/null 2>&1; docker network rm $NET >/dev/null 2>&1; }
cleanup
docker network create $NET >/dev/null
for n in $A $B; do
  docker run -d --name $n --network $NET --cap-add NET_ADMIN alpine sh -c \
    'apk add -q wireguard-tools iproute2 tcpdump netcat-openbsd >/dev/null 2>&1 && touch /ready && sleep 3600' >/dev/null
done
for n in $A $B; do until docker exec $n test -f /ready 2>/dev/null; do sleep 1; done; done
ip_of() { docker inspect -f '{{(index .NetworkSettings.Networks "'$NET'").IPAddress}}' "$1"; }
IPA=$(ip_of $A); IPB=$(ip_of $B)
KA=$(docker exec $A wg genkey); KB=$(docker exec $B wg genkey); KX=$(docker exec $A wg genkey)
PA=$(echo "$KA" | docker exec -i $A wg pubkey); PB=$(echo "$KB" | docker exec -i $B wg pubkey); PX=$(echo "$KX" | docker exec -i $A wg pubkey)

up() {  # up <컨테이너> <개인키> <터널 IP> <상대 공개키> <상대 실제 IP> <상대에게 허용할 주소>
  docker exec -i $1 sh -c "cat > /tmp/k; ip link del wg0 2>/dev/null; ip link add wg0 type wireguard && \
    wg set wg0 listen-port 51820 private-key /tmp/k peer $4 endpoint $5:51820 allowed-ips $6 && \
    ip addr add $3/24 dev wg0 && ip link set wg0 up" <<<"$2"
}
case_run() {  # case_run <이름> <A가 믿는 B의 공개키> <A 가 B에 허용한 주소> <B 가 A에 허용한 주소>
  echo "## $1"
  up $A "$KA" 10.8.0.1 "$2" $IPB "$3"
  up $B "$KB" 10.8.0.2 "$PA" $IPA "$4"
  if docker exec $A ping -c 2 -W 2 10.8.0.2 >/dev/null 2>&1; then OK=1; else OK=0; fi
  docker exec $A wg show wg0 dump | python wg_summary.py --ping $OK; echo "  종료 코드 $?"
}
case_run "1. 정상 설정" "$PB" 10.8.0.2/32 10.8.0.1/32
case_run "2. A 가 B 의 공개키를 잘못 적음" "$PX" 10.8.0.2/32 10.8.0.1/32
case_run "3. B 가 A 의 주소를 잘못 허용함" "$PB" 10.8.0.2/32 10.9.9.9/32

echo "## 4. 겉으로 보이는 패킷에 내용이 있는가(정상 설정으로 복구해 비교)"
up $A "$KA" 10.8.0.1 "$PB" $IPB 10.8.0.2/32
up $B "$KB" 10.8.0.2 "$PA" $IPA 10.8.0.1/32
docker exec -d $B sh -c 'nc -l -p 9000 >/dev/null; true'
docker exec -d $B sh -c 'nc -l -p 9001 >/dev/null; true'
docker exec -d $A sh -c "tcpdump -nn -i eth0 -w /tmp/o.pcap host $IPB >/dev/null 2>&1"
sleep 2
docker exec $A sh -c "echo SECRETMARKER | nc -w 1 10.8.0.2 9000"      # 터널 안으로
docker exec $A sh -c "echo SECRETMARKER | nc -w 1 $IPB 9001"          # 터널 밖으로(일반 TCP)
sleep 1
docker exec $A pkill tcpdump; sleep 1
echo -n "  터널로 보낸 쪽(UDP 51820) 패킷: "; docker exec $A sh -c "tcpdump -nn -r /tmp/o.pcap udp port 51820 2>/dev/null | wc -l"
echo -n "  터널로 보낸 내용이 겉에 보인 횟수(포트 9000): "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9000 2>/dev/null | grep -c SECRETMARKER; true"
echo -n "  터널 밖으로 보낸 내용이 겉에 보인 횟수(포트 9001): "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9001 2>/dev/null | grep -c SECRETMARKER; true"
echo -n "  UDP 51820 패킷 안에 SECRETMARKER: "; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap udp port 51820 2>/dev/null | grep -c SECRETMARKER; true"
echo "## 5. 겉에서 본 패킷 모양"
echo "  [터널] UDP 51820 (처음 3개)"; docker exec $A sh -c "tcpdump -nn -r /tmp/o.pcap udp port 51820 2>/dev/null | head -3 | cut -d' ' -f1-8,10-"
echo "  [터널 밖] TCP 9001 의 내용이 든 줄"; docker exec $A sh -c "tcpdump -nn -A -r /tmp/o.pcap tcp port 9001 2>/dev/null | grep SECRETMARKER | cut -c1-60"
cleanup
echo "## 끝"
```

`wg show wg0 dump`를 읽어 핸드셰이크와 ping 결과로 종료 코드를 정하는 스크립트입니다.

```python
# wg_summary.py
#!/usr/bin/env python3
"""`wg show wg0 dump` 출력을 표준 입력으로 받아 핸드셰이크와 전송량을 보여 주고,
핸드셰이크가 없거나 ping 이 실패하면 종료 코드 1 로 끝낸다.
사용: wg show wg0 dump | python wg_summary.py --ping 0|1   (개인 키가 든 첫 줄은 읽지 않고 버린다)"""
import sys
import time

sys.stdout.reconfigure(encoding="utf-8")
ping_ok = sys.argv[sys.argv.index("--ping") + 1] == "1" if "--ping" in sys.argv else False
lines = [l for l in sys.stdin.read().splitlines() if l.strip()][1:]   # 첫 줄은 인터페이스(개인 키 포함)
if not lines:
    print("  피어 없음")
    sys.exit(1)
shake_ok = False
for l in lines:
    pub, _psk, endpoint, allowed, shake, rx, tx, _ka = l.split("\t")
    age = int(time.time()) - int(shake) if int(shake) else None
    shake_ok = shake_ok or age is not None
    print(f"  피어 {pub[:8]}…  핸드셰이크 {'없음' if age is None else f'{age}초 전'}  받음 {rx}B  보냄 {tx}B  허용 주소 {allowed}")
print(f"  ping {'성공' if ping_ok else '실패'}")
sys.exit(0 if (shake_ok and ping_ok) else 1)
```

## 자주 막히는 곳

| 증상 | 원인 | 해결 |
|---|---|---|
| `ip link add wg0 type wireguard`가 실패 | 커널에 WireGuard가 없거나 권한 부족 | `--cap-add NET_ADMIN`과 커널 지원 확인 |
| 컨테이너가 준비되기 전에 명령이 실패 | `apk add`가 끝나기 전 | 컨테이너 안에 `/ready` 파일을 만들고 기다림 |
| 핸드셰이크가 없음 | 상대 공개키 오류, 포트 차단, `endpoint` 주소 오류 | 공개키와 UDP 51820 도달 여부 확인 |
| 핸드셰이크는 있는데 ping이 실패 | 한쪽의 허용 주소가 상대 터널 주소를 포함하지 않음 | 양쪽 `allowed-ips` 확인 |
| 파이썬이 한글을 못 씀 | Windows 콘솔 기본 인코딩 | `sys.stdout.reconfigure(encoding="utf-8")` |
| `pkill` 뒤 파일이 비어 있음 | tcpdump가 쓰기를 끝내기 전에 읽음 | 종료 신호 뒤 1초 기다림 |

## 확인 범위

- **해 본 것:** 2026-10-30, Windows 11 · Docker 29.5.3 · WSL2 커널 6.6.87.2 · wireguard-tools v1.0.20260223에서 컨테이너 두 개 사이의 터널 생성, 정상 설정(핸드셰이크 있음, ping 성공), 공개키 오류(핸드셰이크 없음), 허용 주소 오류(핸드셰이크 있음, ping 실패), 종료 코드 변환(0, 1, 1), tcpdump로 터널 안과 밖의 문자열 노출 비교(0회 대 1회)를 실행했습니다. 전체 스크립트를 다섯 번 이상 실행했고 1번부터 4번까지의 결과는 매번 같았으며, 끝에 컨테이너와 네트워크를 지웠습니다.
- **해 보지 않은 것:** 서로 다른 호스트 사이의 터널, 포트 포워딩과 NAT 통과, `PersistentKeepalive`, 사전 공유 키, 여러 피어, 클라이언트 앱, 성능 측정, 핸드셰이크 시간 기준, Linux 호스트와 macOS.
- **읽을 때 주의:** 5번 단계에서 터널 패킷을 처음 3개 보여 줄 때, 한 줄만 출력된 적이 한 번 있고 원인은 확인하지 않았습니다. 그 뒤 세 번은 세 줄(148, 92, 96)이 나왔습니다. 키는 매번 새로 만든 시험용이며 실제 환경에서는 개인 키를 명령행에 넘기지 않습니다. 출력과 바이트 수는 이 버전과 이 환경의 값입니다.
