
New releaseSep 12, 2026
pingtunnel master-d7cd0d6ab5f18e7d8d050385e8d240b3b2f41e6c
Pingtunnel은 TCP/UDP 트래픽을 ICMP를 통해 전송하는 도구입니다.
Pingtunnel
Pingtunnel은 ICMP Echo(Ping) 패킷을 통해 TCP/UDP/SOCKS5 트래픽을 터널링하여 엄격한 네트워크 방화벽을 우회하거나 제한된 TCP/UDP 트래픽을 통과시키는 네트워크 도구입니다.
⚠️ 참고: 이 도구는 오직 학습 및 연구 목적으로만 사용해야 합니다. 불법적인 목적으로 사용하지 마십시오.

🌟 주요 기능
- 통합된 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 사용 및 구성 가이드