업데이트로 돌아가기
New releaseSep 12, 2026

pingtunnel master-d7cd0d6ab5f18e7d8d050385e8d240b3b2f41e6c

Pingtunnel은 TCP/UDP 트래픽을 ICMP를 통해 전송하는 도구입니다.

공유

Pingtunnel

codecov

Pingtunnel은 ICMP Echo(Ping) 패킷을 통해 TCP/UDP/SOCKS5 트래픽을 터널링하여 엄격한 네트워크 방화벽을 우회하거나 제한된 TCP/UDP 트래픽을 통과시키는 네트워크 도구입니다.

⚠️ 참고: 이 도구는 오직 학습 및 연구 목적으로만 사용해야 합니다. 불법적인 목적으로 사용하지 마십시오.

image


🌟 주요 기능

  • 통합된 v3 보안 아키텍처: 기존의 숫자 키와 별도의 암호화 스위치는 제거되었습니다. 단일 공유 비밀번호(-password)가 상호 인증과 종단 간 AEAD 암호화(기본값 chacha20-poly1305, 선택 사항 aes256/aes128)를 모두 처리합니다.
  • 다양한 모드:
    • SOCKS5 프록시: 명령 하나로 로컬 SOCKS5 프록시를 시작하며, 선택적으로 사용자 이름/비밀번호 인증을 지원합니다;
    • TCP 포트 포워딩: 특정 원격 TCP 포트(예: SSH, 웹, RDP)에 접근합니다;
    • UDP 포트 포워딩: 게임 UDP 트래픽, DNS 53 등을 포워딩합니다;
    • 서버 측 2차 포워딩(-forward): 서버가 수신 트래픽을 업스트림 SOCKS5/HTTP 프록시를 통해 중계할 수 있습니다.
  • 유연한 구성(구성 파일 모드 권장):
    • 구성 파일로 직접 실행: pingtunnel config.json 또는 pingtunnel -c config.json;
    • 현재 디렉터리의 config.json은 기본적으로 자동 로드됩니다;
    • 명령줄 플래그는 항상 해당 구성 파일 값을 덮어씁니다.
  • 열악한 네트워크에서도 견고함: 내장된 대역폭 적응형 혼잡 제어 알고리즘(bb)이 버퍼블로트와 패킷 손실로 인한 지연을 억제합니다.

🚀 빠른 시작

옵션 1: 구성 파일 모드(권장)

샘플 파일이 저장소에 포함되어 있습니다. 서버 IP와 강력한 비밀번호만 입력하면 됩니다:

1. 서버 구성(config-server.json)

{
  "type": "server",
  "password": "YOUR_STRONG_PASSWORD_HERE",
  "encrypt": "chacha20",
  "icmp_listen": "0.0.0.0"
}

서버를 시작합니다 (root / 관리자 권한 필요):

sudo ./pingtunnel config-server.json
# or: sudo ./pingtunnel -c config-server.json

2. 클라이언트 구성 (SOCKS5 프록시 모드, config-client-socks5.json)

{
  "type": "client",
  "listen": "127.0.0.1:1080",
  "server": "YOUR_SERVER_IP",
  "socks5": true,
  "password": "YOUR_STRONG_PASSWORD_HERE",
  "encrypt": "chacha20"
}

클라이언트를 시작합니다:

./pingtunnel config-client-socks5.json
# or: ./pingtunnel -c config-client-socks5.json

그런 다음 브라우저 또는 시스템 프록시를 SOCKS5 127.0.0.1:1080으로 설정하세요.


옵션 2: 명령줄 (CLI)

1. 서버 시작

공인 IP가 있는 머신에서 실행하세요:

sudo ./pingtunnel -type server -password YOUR_STRONG_PASSWORD_HERE

(선택 사항) 간섭을 피하기 위해 Linux 커널의 기본 ICMP 에코 응답을 비활성화합니다:

echo 1 > /proc/sys/net/ipv4/icmp_echo_ignore_all

2. 클라이언트 시작

  • SOCKS5 프록시 모드:
    ./pingtunnel -type client -l 127.0.0.1:1080 -s YOUR_SERVER_IP -socks5 -password YOUR_STRONG_PASSWORD_HERE
    
  • TCP 포트 포워딩 (기본 모드, 예: 원격 내부 192.168.1.100:22를 로컬 포트 2222에 매핑):
    ./pingtunnel -type client -l :2222 -s YOUR_SERVER_IP -t 192.168.1.100:22 -password YOUR_STRONG_PASSWORD_HERE
    
  • UDP 포워딩 (예: 로컬 포트 5353에서 공용 DNS 8.8.8.8:53으로):
    ./pingtunnel -type client -l :5353 -s YOUR_SERVER_IP -t 8.8.8.8:53 -udp -password YOUR_STRONG_PASSWORD_HERE
    

🐳 Docker

서버 실행

docker run --name pingtunnel-server -d \
  --restart=always \
  --privileged \
  --network host \
  esrrhs/pingtunnel ./pingtunnel -type server -password YOUR_STRONG_PASSWORD_HERE

마운트된 구성 파일로 실행

docker run --name pingtunnel-server -d \
  --restart=always \
  --privileged \
  --network host \
  -v /etc/pingtunnel/server.json:/app/server.json:ro \
  esrrhs/pingtunnel ./pingtunnel /app/server.json

📖 상세 사용법 및 튜닝 가이드

고급 옵션과 토폴로지(서버 측 보조 프록시, 포트 포워딩, SOCKS5 인증, 흐름 제어 및 혼잡 튜닝)에 대해서는 다음을 참조하세요: 👉 USAGE.md - Pingtunnel 사용 및 구성 가이드

카테고리