🌐 English | 中文 | 한국어

라우터 시스템

HY2 SCALE은 Docker를 지원하는 라우터 시스템에서의 실행을 지원합니다. 커스텀 또는 경량화된 Linux 커널을 사용하는 장치에서도 작동합니다. 이러한 환경은 비표준 netfilter 모듈이나 제한된 iptables를 가지고 있을 수 있으며, HY2 SCALE이 호환 모드를 통해 자동으로 처리합니다.

라우터 시스템에서의 배포

권장: 비호스트 네트워크

docker run -d --name hy2scale \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

참고: --privileged가 필요하지 않습니다. NET_ADMIN + NET_RAW 권한이면 충분합니다.

표준 Linux와의 차이점

항목	표준 Linux	라우터 시스템
네트워크 모드	--network host	고정 IP의 브리지 네트워크
iptables	정상 작동	작동하지 않을 수 있음 (커스텀 커널 모듈)
L2TP 모드	iptables DNAT	TUN 캡처 + gvisor netstack
IKEv2 모드	iptables DNAT	xfrm 브리지 + AF_PACKET
라우팅 규칙	iptables DNAT	사용 불가
권한	NET_ADMIN	NET_ADMIN + NET_RAW
TUN 디바이스	자동 생성	--device /dev/net/tun 필요

호환 모드 작동 방식

자동 감지

HY2 SCALE은 testIptablesAvailable()을 사용하여 제한된 환경을 자동으로 감지합니다:

testIptablesAvailable()
├── true  → 표준 경로 (iptables DNAT + 투명 프록시)
└── false → 호환 경로 (TUN/xfrm + gvisor netstack)

이 함수는 iptables-legacy -t nat -L -n이 성공하는지 테스트합니다. 커스텀 커널을 가진 라우터 시스템에서는 실패할 수 있습니다:

• 커널에 표준 iptables가 인식하지 못하는 독자적 netfilter 타겟이 포함됨
• 표준 iptables 바이너리가 이러한 커스텀 타겟을 파싱할 수 없음

설정이 필요하지 않습니다 — 호환 모드는 자동으로 활성화됩니다. 표준 Linux에서는 호환 코드가 실행되지 않습니다.

L2TP 호환 모드

표준 L2TP는 iptables를 사용하여 PPP 트래픽을 투명 프록시로 DNAT합니다. 호환 모드에서는 다음으로 대체됩니다:

PPP 클라이언트
  ↓ (L2TP/IPsec 터널)
xl2tpd + pppd (풀에서 IP 할당)
  ↓
정책 라우팅: ip rule from 192.168.25.0/24 lookup TABLE_Y
  ↓
커널 TUN 인터페이스 (hy2cap0)
  ↓
gvisor netstack (TCP/UDP 포워더)
  ↓
메시를 통한 출구 라우팅

1. 정책 라우팅이 PPP 서브넷 트래픽을 라우팅 테이블로 전달
2. 라우팅 테이블이 커널 TUN 디바이스 (hy2cap0)를 통해 트래픽 전송
3. gvisor netstack이 TUN에서 패킷을 읽고 TCP/UDP 처리 제공
4. TCP/UDP 포워더가 연결을 사용자에 매핑하고 출구 라우팅 적용

IKEv2 호환 모드

표준 IKEv2는 iptables를 사용하여 xfrm 인터페이스 트래픽을 DNAT합니다. 호환 모드에서는 다음으로 대체됩니다:

IKEv2 클라이언트
  ↓ (IKE + ESP 터널, UDP 500+4500)
strongSwan (xfrm 인터페이스 생성: ikec0, ikec1, ...)
  ↓
AF_PACKET raw 소켓이 디캡슐화된 패킷 캡처
  ↓ (PACKET_OUTGOING 필터링으로 루프 방지)
gvisor netstack (TCP/UDP 포워더)
  ↓
메시를 통한 출구 라우팅
  ↓
응답: raw IP 소켓 → xfrm 인터페이스 → 커널 ESP 캡슐화

1. strongSwan이 각 터널에 대해 xfrm 인터페이스 생성 (if_id_in/out = %unique)
2. **AF_PACKET (SOCK_RAW)**이 xfrm 인터페이스에서 디캡슐화된 패킷 캡처
3. PACKET_OUTGOING 패킷은 캡처 루프 방지를 위해 필터링
4. gvisor netstack이 TCP/UDP를 처리하고 출구 라우팅 적용
5. 응답이 xfrm 인터페이스를 통해 다시 주입되어 ESP 캡슐화

이 접근법은 비호스트 컨테이너 네트워크 네임스페이스에서 차단되는 FORWARD 체인을 완전히 우회합니다.

MTU 설정

라우터 시스템 배포는 ESP 오버헤드를 수용하기 위해 낮은 MTU 값을 사용합니다:

프로토콜	표준 MTU	라우터 시스템 MTU
L2TP	1280	1280
IKEv2	1400	1300

라우터 시스템에서의 IKEv2 MSCHAPv2

IKEv2 MSCHAPv2 모드는 라우터 내장 IKEv2 클라이언트와 호환됩니다:

1. TLS 페이지에서 CA 인증서 업로드
2. MSCHAPv2 모드로 IKEv2 활성화
3. HY2 SCALE이 CA를 사용하여 서버 인증서 자동 서명
4. 라우터의 IKEv2 클라이언트에 CA 인증서와 사용자 자격 증명 설정

문제 해결

VPN 서비스가 "Limited"로 표시

이는 iptables를 사용할 수 없음을 의미합니다. 라우터 시스템에서는 예상되는 동작입니다 — 호환 모드가 VPN 트래픽을 다르게 처리합니다. "Limited" 배지는 표준 모드 VPN 기능이 불가하지만 호환 모드 대체 기능이 활성화되어 있음을 나타냅니다.

L2TP/IKEv2가 작동하지 않음

1. 권한 확인: NET_ADMIN과 NET_RAW가 모두 설정되었는지 확인
2. TUN 디바이스 확인: --device /dev/net/tun이 전달되었는지 확인
3. 디버그 모드 (DEBUG=true) 활성화 후 로그 확인:
   • iptables available: false — 호환 모드 활성화 확인
   • TUN 디바이스 생성 메시지
   • xfrm 인터페이스 생성 메시지

LAN 클라이언트에서 연결 불가

브리지 네트워크 모드 사용 시 확인:

1. 컨테이너에 Docker 네트워크의 고정 IP가 있는지
2. 라우터에 Docker 네트워크로의 라우트가 있는지
3. VPN 포트 (500, 4500, 1701)에 대한 포트 포워딩이 설정되었는지

디버그 로깅

docker run -d --name hy2scale \
  -e DEBUG=true \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

디버그 모드 로그:

• iptables 감지 결과
• 권한 및 호스트 네트워크 확인
• TUN 디바이스 읽기/쓰기 작업
• AF_PACKET 패킷 캡처
• gvisor netstack 포워더 연결
• 정책 라우팅 테이블 설정

라우터 재부팅 후 복구

라우터 재부팅 후 Docker 컨테이너가 재시작되지만 네트워크 설정이 손실될 수 있습니다. 확인 사항:

1. Docker 네트워크가 올바른 서브넷으로 재생성되었는지
2. 컨테이너가 --restart unless-stopped를 사용하는지
3. 고정 IP가 Docker 네트워크 범위 내에 있는지

재부팅 후 컨테이너 시작에 실패하면, 설정을 보존하기 위해 동일한 볼륨 마운트로 컨테이너를 삭제하고 다시 생성하세요.